I'm becoming somewhat suspicious of both REST and GraphQL for APIs. Not in the sense of thinking that they're bad or antipatterns or anything so hyperbolic as that, but in that they make some fundamental assumptions about how APIs are going to work that I don't think we should ever just take for granted.
On the REST side, it's the assumption that the API is for state transfers. Transfer is a heavy word there. You're not just assuming that the service is stateful, and you're not just assuming that clients can ask for state changes. You're assuming that the dominant model for effectuating those state changes is that the client determines what the new state should look like, and transfers a representation of that state to the server.
And then, on the GraphQL side, you're assuming that the service is basically just a big database. Perhaps one with lots and lots and lots of behavior that, from a high level, looks a lot like triggers. But still, a database.
Both these assumptions may work well for a whole lot of applications. If CRUD's your ticket, then both can serve you well. But choosing either might force you to make some compromises if you were instead hoping to do come up with, for example, a more domain-driven design.
What is commonly referred to as “REST” isn’t actually REST, and trying to cram that round peg into that square hole is a hobgoblin of little minds IMO. In practice, “REST” can be simplified to RPC over HTTP using JSON as a wire format. Or you can use gRPC and get strong typing and explicit RPC semantics instead.
It's not just using JSON as a wire format, it's overloading HTTP verbs and status codes as part of your protocol.
HTTP verbs and status codes map fairly cleanly to CRUD and, more generally, the "state transfer" paradigm. For generic RPC, though? Tends to get quite a bit messier.
While that’s true in the general case, there’s some rules of thumb that get you most of the way there. Use GET for read-only, side-effect-free operations and POST for everything else. Return 2xx for success, 4xx for “client error”, and 5xx for “server error”. Use Swagger to document payload formats and expected response codes. Getting too much farther beyond that is a slippery slope that leads straight to the REST hobgoblin, who is a mere distraction from the dragons a service owner actually needs to battle.
Comments
I'm becoming somewhat suspicious of both REST and GraphQL for APIs. Not in the sense of thinking that they're bad or antipatterns or anything so hyperbolic as that, but in that they make some fundamental assumptions about how APIs are going to work that I don't think we should ever just take for granted.
On the REST side, it's the assumption that the API is for state transfers. Transfer is a heavy word there. You're not just assuming that the service is stateful, and you're not just assuming that clients can ask for state changes. You're assuming that the dominant model for effectuating those state changes is that the client determines what the new state should look like, and transfers a representation of that state to the server.
And then, on the GraphQL side, you're assuming that the service is basically just a big database. Perhaps one with lots and lots and lots of behavior that, from a high level, looks a lot like triggers. But still, a database.
Both these assumptions may work well for a whole lot of applications. If CRUD's your ticket, then both can serve you well. But choosing either might force you to make some compromises if you were instead hoping to do come up with, for example, a more domain-driven design.
What is commonly referred to as “REST” isn’t actually REST, and trying to cram that round peg into that square hole is a hobgoblin of little minds IMO. In practice, “REST” can be simplified to RPC over HTTP using JSON as a wire format. Or you can use gRPC and get strong typing and explicit RPC semantics instead.
It's not just using JSON as a wire format, it's overloading HTTP verbs and status codes as part of your protocol.
HTTP verbs and status codes map fairly cleanly to CRUD and, more generally, the "state transfer" paradigm. For generic RPC, though? Tends to get quite a bit messier.
While that’s true in the general case, there’s some rules of thumb that get you most of the way there. Use GET for read-only, side-effect-free operations and POST for everything else. Return 2xx for success, 4xx for “client error”, and 5xx for “server error”. Use Swagger to document payload formats and expected response codes. Getting too much farther beyond that is a slippery slope that leads straight to the REST hobgoblin, who is a mere distraction from the dragons a service owner actually needs to battle.