Nate Barbettini, Senior Developer Evangelist at Okta tackled a potentially divisive subject at one of the "build" breakout sessions at the Okta Iterate Developers Conference. While the title of Nate's presentation was "API Throwdown: RPC vs. REST vs. GraphQL," his goal was to explore the strengths and weaknesses of each style and help developers be open to selecting the right style to solve the problem they are facing.

There's a debate raging over which API style is best, but Nate doesn't feel like that's a valuable debate to be having and he doesn't see a linear progression from RPC to REST to GraphQL. There are different designs for different uses based on the following design considerations:

• Coupling
• Chattiness
• Client complexity
• Cognitive complexity
• Caching
• Discoverability
• Versioning

Developers need to understand the practical tradeoffs of each style before making a decision on which style is right for the project they are working on.

Here's his comparison:

RPC – remote procedure call -- began being used in the 1970s or 1980s. It enables “Call a function on another server.” Its fundamental unit is a "Function." It fits with action-oriented APIs with service definitions, GET /listConversations, Reply to conversation. The cutting edge of RPC is Apache Thrift, gRPC, and Twirp for high performance, low overhead messaging. The advantages of RPC are: 1) simple and easy to understand; 2) lightweight payloads; and, 3) high performance. Problems include: 1) tight coupling; 2) no discoverability – how do I know how to start, what to call; 3) function explosion – so easy to create new functions you do that all the time; 4) hard to understand and maintain; and, 5) need better abstraction between the underlying system and the API

REST – representational state transfer -- is the opposite of a tightly coupled API. It enables, “Here are some resources and what you can do with them.” Its fundamental unit is a "Resource." It has a clear entry point, get all conversations, a style more like the web works rather than calling functions. Without additional documentation, you can understand how to use the API: Describe operations on resources, Get author info, Get recent conversations + replies + authors, REST ! over HTTP, REST != “RESTful procedure call.” Hypertext serves as the engine of application state. Its goal is to decouple the client and the server. The cutting edge of REST is: HAL, JSON-API, and Ion. Its advantages are: 1) decouple client and server; 2) the API can evolve over time; 3) it reuses HTTP. Problems include: 1) no single spec on how they should be built; 2) big payloads and “chattiness.”

GraphQL – Graph query language -- enables you to “Ask for exactly what you want.” The fundamental unit is a "query." It includes a schema definition, a description of all queries you can make. It enables you to get all conversations and messages, get all conversations + messages + author names, in one call versus 10 calls with REST, and reply to a conversation. The advantages are: 1) low network overhead; 2) typed schema; 3) fits graph-like data very well. Problems include: 1) complexity – more powerful but more complex; 2) caching; 3) versioning – awkward state of best practice; 4) still early in development and application.

Use case scenarios:

• Management API
  • Focus on objects or resources
  • Many varied clients
  • Discoverability and documentation
  • Consider: REST (Ion, HAL, JSON-PI)
• Command API
  • Action-oriented
  • Simple interactions
  • Consider: RPC
• Microservices
  • High message rate
  • Low overhead
  • Consider RPC (gRPC, Twirp) or REST
• Data or Mobile API
  • Data is graph-like
  • Optimize for high latency
  • Consider: GraphQL

Key takeaways regarding APIs:

1. There's no silver bullet.

2. For every API project, there are different requirements and different needs.

3. Understand what patterns fit the use case best.

To learn more, check out:

• YouTube: Les Hazlewood on REST API design
• YouTube: Eric Baer on GraphQL
• Phil Sturgeon’s blog: https://philsturgeon.uk
• APIs You Won't Hate