Using Response Codes: REST vs. GraphQL

It feels like people are fairly confused about the numbers and some are saying, its easier in GraphQL. What a lot of people misunderstand about the 200 jokes about GraphQL is, 200 OK with a Graph QL API means, the server was able to process your request without exploding.

With GraphQL you have interfaces and you have union types where you can be very explicit about what kind of response you give to the user. So basiaclly, you don)t really have to worry about codes.

However, the problem is people missunderstanding in which situations you build a GrapHQL and in which REST API.

There’s one very important distinction we have to make between REST and GraphQL. With REST it always the case that the producer of the API can make intent very clear. With GraphQL you actually need to understand the API you want to access. So you’ll have to go to GitHub docs and you want to understand how to get information, you look that up in the docs, and it gives you exactly the endpoint you want to interact with. And with GraphQL you get 10MB of GraphQL schema and now you have to figure out how to formulate your query.

So, from my point of view GraphQL is a lot easier when you produce the API for yourself, whereas with REST you can make intent to 3rd parties much more clear because you have clear entry points, you have URLs with a specific intent and with GraphQL you have one endpoint and then you have a query and they have 50 different fields and you might be a bit overwhelmed and you don’t exactly know where to start.

So if your API is going to get consumers, REST is a better option.

In GraphQL if you’re doing errors as data, you have to figure out how to relay that problem scenario to the client and that is always going to be a unique, snowflake situation. You are going to have to come up with your own error codes that you agree with them.

But that doesn’t work for generic monitoring tools, that doesn’t work for lots of other things.

I really like in REST that I can use status codes as a category of error.

Which will let caching tools know not to recache it, will let monitoring tools know that there was some sort of problem, will let people know if they should retry or not. Those categories of error should be fairly understood.

And then within the message, you can use something like RFC 787 or JSON API errors with really standard error formats where you go just as specific with what went wrong. Dynamic information, various different variables and arguments and messages that are written in English or you can even have them translated.

You can do both in REST and I feel like that gets ignored from the conversation and people just talk about 400 and 409, 406 and get confused about the numbers.