REST/RPC/GraphQL

REST

Pros

1. Good for exposing CRUD operations.

2. Easiest to maintain compared to others.

3. Standard method names, arguments and status codes.

4. Utilizes HTTP features.

Cons

1. Payload is big 

   1. JSON which is human readable.

   2. Getting the entire User entity while I need the user's first and last name only.

2. Multiple HTTP roundtrips.

   1. If you want to get a resource and its sub resource, you need to make a call for the resource and then another call for the sub resource. There is no way to combine the two calls into one in a RESTful way.

RPC

Notes

1. It’s all about actions

2. Example slack.

3. Usually supports GET for read only requests and POST for everything else.

4. Very popular among API providers recently.

5. gRPC.

Pros

1. Good for exposing several actions.

2. Small Payload

   1.  Because it’s in binary.

   2. Payload is associated with the action itself, so only the required data is transmitted.

3. High performance because they are action oriented.

4. Easy to understand as the action is usually the part of the request.

5. Github.

Cons

1. Difficult to discover.

2. Limited standardization. Referencing documentation is important.

3. Function explosion.

GraphQL

Notes

1. Developed by Facebook.

2. Expose a single endpoint as an entry point.

3. Client then specifies what they need.

Pros

1. Good when the client needs filtering/flexibility.

2. Small payload because the response contains only the data client needs.

3. Clients can request multiple nested levels of data.

4. Don’t need versioning. 

Cons

1. Complexity on the server.

2. Optimizing performance can be difficult.

   1. Working with external users, it becomes difficult to identify different use cases.

3. Too complicated for simple APIs.