RPC VS. REST VS. GraphQL

Transcription

1 RPC VS. REST VS. GraphQL An API throwdown February 27, 2018

2 WHICH API STYLE IS BEST? {

3 THE DEBATE IS STILL RAGING

4 DEBATES MISS THE POINT

5 API DESIGN EVOLUTION? NOT QUITE. REST RPC

6 Coupling Chattiness Client complexity Cognitive complexity Caching Discoverability Versioning { MANY DESIGN CONSIDERATIONS

7 GOAL: Understand the practical tradeoffs

8 RPC Remote procedure call

9 "Call a function on another server" Fundamental unit: function

10 RPC API EXAMPLE Service definition listconversations(); listmessages(int conversationid); sendmessage(int conversationid, string body);

11 RPC API EXAMPLE Service definition GET /listconversations GET /listmessages?id=123 POST /sendmessage?id=123

12 RPC API EXAMPLE Get all conversations GET /listconversations [ { "id": 2, "title": "vi or emacs?", "author": 1008,... ]

13 RPC API EXAMPLE 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 ]

14 RPC API EXAMPLE Reply to conversation POST /sendmessage?id=2 { "body": "Editor debates are silly"

15 Cutting edge of RPC Apache Thrift grpc Twirp

16 ADVANTAGES OF RPC Simple and easy to understand Lightweight payloads High performance

17 PROBLEMS WITH RPC Tight coupling No discoverability Function explosion

18 FUNCTION EXPLOSION /listconversations /listconversationsv2 /listmessages /sendmessage /sendmessagertl /checksendstatus /getauthordetails /getauthordetailsv2 /getfullauthordetailsv3 /deletemessage /deletemessageadmin /gettopconversations /gettopconversationsv2 /getsystemstatus

19 REST Representational state transfer

20 "Here are some resources and what you can do with them" Fundamental unit: resource

21 { "conversations": { "href": " "rel": [ "collection" ], "desc": "View all conversations", "messages:" { "href": " "rel": [ "collection" ] REST API EXAMPLE Entry point GET

22 REST API EXAMPLE Get all conversations GET { "count": 2, "value": [ { "href": " "title": "vim or emacs?", "author": " "messages": " ]

23 REST API EXAMPLE Get all messages in a conversation GET { "count": 3, "value": [ { "href": " "conversation": " "text": "Real programmers use Notepad.", "author": " ]

24 REST API EXAMPLE Describe operations on resources "create": { "href": " "method": "POST", "desc": "Reply to conversation", "value": [ { "name": "text", "desc": "Your reply" ]

25 REST API EXAMPLE Reply to a conversation POST { "text": "Editor debates are silly"

26 REST API EXAMPLE Get author info GET { "href": " "name": "Joe Brogrammer", "location": "None of your business", "messages": { "href": " "rel" [ "collection" ], "desc": "View user's messages"

27 REST API EXAMPLE Get recent conversations + replies + authors GET GET GET GET GET GET GET

28 REST!= JSON over HTTP REST!= "RESTful procedure call"

29 Hypertext As The Engine Of Application State Goal: decouple the client and server

30 Cutting edge of REST HAL JSON-API Ion

31 ADVANTAGES OF REST Decoupled client and server API can evolve over time Reuses HTTP

32 PROBLEMS WITH REST No single spec Big payloads and "chattiness"

33 REST API "CHATTINESS" GET GET GET GET GET GET GET

34 GraphQL Graph query language

35 "Ask for exactly what you want" Fundamental unit: query

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

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." ] ]

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" ] ]

39 GRAPHQL API EXAMPLE Reply to a conversation mutation { sendmessage(text: "vscode is best") { id { "data": { "sendmessage": { "id": "103"

40 ADVANTAGES OF GRAPHQL Low network overhead Typed schema Fits graph-like data very well

41 Complexity PROBLEMS WITH GRAPHQL Caching Versioning Still early

42 DESIGN CONSIDERATIONS 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???

43 THE DEBATE IS STILL RAGING WHICH API STYLE IS BEST? WHO USES MY API?

44 USE CASE: MANAGEMENT API Focus on objects or resources Many varied clients Discoverability and documentation Consider: REST (Ion, HAL, JSON-API)

45 USE CASE: COMMAND API Action-oriented Simple interactions Consider: RPC

46 USE CASE: MICROSERVICES High message rate Low overhead Consider: RPC (grpc, Twirp) or REST

47 USE CASE: DATA OR MOBILE API Data is graph-like Optimize for high latency Consider: GraphQL

48 NO SILVER BULLET

49 LEARN MORE YouTube: Les Hazlewood on REST API design YouTube: Eric Baer on GraphQL Phil Sturgeon's blog: