Hey Cure, great post. I agree with most of the points you have made (and here’s proof: https://firstname.lastname@example.org/graphql-from-a-rest-perspective-e255d2073a30), but not 100%. Let’s start:
- Documentation: I firmly believe that neither swagger nor GraphQL’s schema definition get close to providing proper API documentation (last section here: https://email@example.com/api-design-fundamentals-the-contract-5f89a6bf8988). If you want people to use your API, you need some sort of contract but, perhaps more importantly you need narrative docs. To make things murkier, there’s lots of REST purists out there that say swagger is not RESTful. So I’m really not sold on this one…
- HTTS Status/Verbs: good point, to be taken with a grain of salt, though. Many people out there believe that REST adherence means CRUD, after all, verbs such as GET, PUT, POST and DELETE kind of map to it, right?
- Caching: a fair point, but perhaps not as big as one would think — in mobile clients, for example, the most important cache needs to take place on the client side and for that, there’s a lot of tooling around GraphQL;
- HATEOAS/Hypermedia: to me, these two points are two sides of the same coin and represent the biggest loss in GraphQL;
At the end of the day, my biggest point is: how many truly RESTful APIs exist out there? I know from experience how hard it is to implement proper HATEOAS and can fully appreciate why many teams do not really do it. So in my mind, the fairest comparison should be between GraphQL and REST as we see it, not as it should ideally be.