API throwdown: RPC vs. REST vs. GraphQL

API throwdown: RPC vs. REST vs. GraphQL

Choosing an API design paradigm can be hard. The colorful debates on Twitter about which API style is "best" make it even harder. In this talk, I break down the three popular styles today (RPC, REST, GraphQL), weigh their strengths and weaknesses, and discuss when each makes sense.

3662c6afc9e95019ec22a44410fa226f?s=128

Nate Barbettini

March 08, 2018
Tweet

Transcript

  1. 12.

    Get all conversations GET /listConversations [ { "id": 2, "title":

    "vi or emacs?", "author": 1008 }, ... ] RPC API EXAMPLE
  2. 13.

    Get all messages in a conversation GET /listMessages?id=2 [ {

    "id": 100, "message": "Atom", "author": 3001 }, { "id": 101, "message": "Real programmers use Notepad.", "author": 3009 } ] RPC API EXAMPLE
  3. 20.

    "Here are some resources and what you can do with

    them" Fundamental unit: resource
  4. 21.

    REST API EXAMPLE Entry point GET https://api.example.io/ { "conversations": {

    "href": "https://api.example.io/conversations", "rel": [ "collection" ], "desc": "View all conversations" }, "messages:" { "href": "https://api.example.io/messages", "rel": [ "collection" ] } }
  5. 22.

    REST API EXAMPLE Get all conversations GET https://api.example.io/conversations { "count":

    2, "value": [ { "href": "https://api.example.io/conversations/2", "title": "vim or emacs?", "author": "https://api.example.io/users/1008", "messages": "https://api.example.io/conversations/2/messages" }, ... ]
  6. 23.

    REST API EXAMPLE Get all messages in a conversation GET

    https://api.example.io/conversations/2/messages { "count": 3, "value": [ { "href": "https://api.example.io/messages/101", "conversation": "https://api.example.io/conversations/2", "text": "Real programmers use Notepad.", "author": "https://api.example.io/users/3009" }, ... ] }
  7. 24.

    REST API EXAMPLE Describe operations on resources "create": { "href":

    "https://api.example.io/conversations/2/messages", "method": "POST", "desc": "Reply to conversation", "value": [ { "name": "text", "desc": "Your reply" } ] } }
  8. 26.

    REST API EXAMPLE Get author info GET https://api.example.io/users/3009 { "href":

    "https://api.example.io/users/3009", "name": "Joe Brogrammer", "location": "None of your business", "messages": { "href": "https://api.example.io/users/3009/messages", "rel" [ "collection" ], "desc": "View user's messages" }
  9. 27.

    REST API EXAMPLE Get recent conversations + replies + authors

    GET https://api.example.io/conversations GET https://api.example.io/conversations/1 GET https://api.example.io/conversations/1/messages GET https://api.example.io/users/214 GET https://api.example.io/conversations/2 GET https://api.example.io/conversations/2/messages GET https://api.example.io/users/3009
  10. 33.

    REST API "CHATTINESS" GET https://api.example.io/conversations GET https://api.example.io/conversations/1 GET https://api.example.io/conversations/1/messages GET

    https://api.example.io/users/214 GET https://api.example.io/conversations/2 GET https://api.example.io/conversations/2/messages GET https://api.example.io/users/3009
  11. 36.

    GRAPHQL API EXAMPLE Schema definition type Query { listConversations: [Conversation]

    } type Mutation { sendMessage(text: String): Message } type Conversation { id: Int title: String messages: [Message] } type Message { id: ID text: String author: User } type User { id: ID name: String }
  12. 37.

    GRAPHQL API EXAMPLE Get all conversations and messages { listConversations

    { title, messages { text } } } { "data": { "listConversations": [ { "title": "vim or emacs?", "messages": [ { "text": "Real programmers use Notepad." } ] } ] } }
  13. 38.

    GRAPHQL API EXAMPLE Get all conversations + messages + author

    names { listConversations { title, messages { text, author { name } } } } { "data": { "listConversations": [ { "title": "vim or emacs?", "messages": [ { "text": "Real programmers use Notepad." "author": { "name": "Joe Brogrammer" } } ] } ] } }
  14. 39.

    GRAPHQL API EXAMPLE Reply to a conversation mutation { sendMessage(text:

    "vscode is best") { id } } { "data": { "sendMessage": { "id": "103" } } }
  15. 42.

    Coupling Chattiness Client complexity Cognitive complexity Caching Discoverability Versioning RPC

    Functions ▪ High ▪ Medium ▪ Low ▪ Low ▪ Custom ▪ Bad ▪ Hard REST Resources ▪ Low ▪ High ▪ Medium ▪ Low ▪ HTTP ▪ Good ▪ Easy GraphQL Queries ▪ Medium ▪ Low ▪ High ▪ High ▪ Custom ▪ Good ??? DESIGN CONSIDERATIONS
  16. 44.

    USE CASE: MANAGEMENT API Focus on objects or resources Many

    varied clients Discoverability and documentation Consider: REST (Ion, HAL, JSON-API)
  17. 47.

    USE CASE: DATA OR MOBILE API Consider: GraphQL Data is

    graph-like Optimize for high latency
  18. 49.

    LEARN MORE • YouTube: Les Hazlewood on REST API design

    • YouTube: Eric Baer on GraphQL • Phil Sturgeon's blog: https://philsturgeon.uk • https://apisyouwonthate.com