API Approaches: An Overview

A brief look at the most popular approaches for APIs

1. API Approaches: An Overview Te c h n o l o g y L u n c h / O n l i n e / 2 0 2 1 - 0 6 - 1 5 STEFAN TILKOV @STILKOV
2. Disclaimer This talk features •gross oversimpli f ications, •ludicrous exaggerations, •personal takes, •questionable analogies and •a thorough lack of attention to detail but we only have 45 minutes. !
3. Overview of API styles •(g)RPC •HTTP Web APIs •Hypermedia REST APIs •GraphQL •0-API
4. a.k.a. CORBA’s cooler grandkid gRPC
5. Best of four decades of remote procedure calls on one slide DCE/RPC Sun RPC CORBA MSRPC RMI Hessian Burlap .NET Remoting DCOM APPC Thrift SOAP XML-RPC JSON-RPC Ice
6. Remote Procedure Call (in general) Interface Description Logical Communication IDL Compiler Client Server Lib Physical Communication Lib (De-)Serialization Skel Stub (De-)Serialization
7. General RPC issues •Tight coupling between client and server •Dangerous location transparency illusion •Need for re-deployment synchronization •Incompatibilities after version changes •Unsuited for unknown/unexpected clients
8. gRPC characteristics •Coupling between client and server via contract •Based on Google Protocol Buffers data format and HTTP/2 •Widely used within Google and in many projects (e.g. Kubernetes) •.proto f iles de f ine services, requests, responses •Field indexes support (limited) compatibility between different versions •Support for streaming
9. Bene f its gRPC Use for ef f icient, tightly coupled, internal communication within distributed apps •High performance and throughput •Ef f icient resource usage •Mature implementation •Reasonable serialization •Static contract language
10. gRPC Avoid for public APIs, unless you really need it and are willing to ship SDKs Downsides •No generic semantics •Tight coupling •Limited compatibility •Static relationships •High demand on consumers •Static contract language
11. like REST, but not really HTTP Web APIs
12. updateQuote() cancelSubscription() f indMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers() getOrderDetails()
13. updateQuote() cancelSubscription() f indMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers() getOrderDetails() GET PUT POST DELETE
14. URI Method Meaning http://ex.org/v1/customers POST create new customer http://ex.org/v1/customers/{id} GET get customer details http://ex.org/v1/customers/{id}/orders GET get list of customer’s details ... ... ...
15. HTTP API characteristics •Use of HTTP semantics •URI-focused •Strong focus on server-side logic •Standard formats: JSON, XML, URI Templates, … •API description using OpenAPI/Swagger
16. Bene f its HTTP APIs Use as default for simple open APIs (but consider REST) •Ease of use •Generic semantics •Mature infrastructure •Tool support (esp. documentation) •Widely accepted •Low demand on consumers •No standard contract language
17. URI Method Meaning http://ex.org/v1/customers POST create new customer http://ex.org/v1/customers/{id} GET get customer details http://ex.org/v1/customers/{id}/orders GET get list of customer’s details ... ... ... Documented URIs become APIs Versions in URIs cause change for no good reason Assumptions about server details become facts
18. HTTP APIs Avoid for public APIs you expect to maintain for a longer time Downsides •Tight(er) coupling •Limited compatibility •Static relationships •No standard contract language
19. a.k.a. REST APIs Hypermedia REST APIs
20. REST characteristics •Basis for RESTful HTTP APIs: Using HTTP correctly •Strong focus on server-side logic •Dynamic interaction based on hypermedia affordances: Links, link relationships, dynamic forms •Runtime discovery instead of development-time hard-coding •Evolvability via additional resources •Standard formats: JSON-LD, HAL, JSON-API, Siren, …
21. How to turn an HTTP API into a REST API in 3 easy steps
22. Step 1: Service Documents
23. <?xml version="1.0" encoding="UTF-8"?> <serviceDescription xml:base="http://om.example.com"> <link rel="all" href="/orders/" /> <link rel="received" href="/orders/received/" /> <link rel="accepted" href="/orders/accepted/" /> <link rel="rejected" href="/orders/rejected/" /> <link rel="cancelled" href="/orders/cancelled/" /> <link rel="fulfilled" href="/orders/fulfilled/" /> <link rel="cancellations" href="/cancellations/" /> <link rel="reports" href="/reports/" /> </serviceDescription> <link rel="fulfilled" href="http://om.archive.com/orders/" /> { "serviceDescription" : {
 "base": "http://om.example.com",
 "links": [
 { "rel": "all", "href": "/orders/" },
 { "rel": "all", "href": "/orders/" },
 { "rel": "received", "href": "/orders/received/" },
 { "rel": "accepted", "href": "/orders/accepted/" },
 { "rel": "rejected", "href": "/orders/rejected/" },
 { "rel": "cancelled", "href": "/orders/cancelled/" },
 { "rel": "fulfilled", "href": "/orders/fulfilled/" },
 { "rel": "cancellations", "href": "/cancellations/" },
 { "rel": "reports", "href": "/reports/" }
 ]
 }
 }
24. {
 "resources": {
 "http://example.org/rel/widgets": {
 "href": "/widgets/"
 },
 "http://example.org/rel/widget": {
 "href-template": "/widgets/{widget_id}",
 "href-vars": {
 "widget_id": "http://example.org/param/widget"
 },
 "hints": {
 "allow": ["GET", "PUT", "DELETE", "PATCH"],
 "representations": ["application/json"],
 "accept-patch": ["application/json-patch"],
 "accept-post": ["application/xml"],
 "accept-ranges": ["bytes"]
 }
 }
 }
 } https://mnot.github.io/I-D/json-home/
25. Step 2: Resource Links
26. GET /order/123 {
 "order": {
 "date": "2013-07-02",
 "total": 1240.02,
 "..." : "...",
 "links" : [
 {"rel" : "self", "href" : "http://example.com/orders/123"},
 {"rel" : "contacts", "href" : "http://example.org/A3BEF1"},
 ...
 ] }
 }
27. GET /order/123 {
 "order": {
 "date": "2013-07-02",
 "total": 1240.02,
 "..." : "...",
 "links" : {
 "self": "http://example.com/orders/123",
 "contacts": "http://example.org/A3BEF1",
 ...
 } }
 } Your future extensions
28. Step 3: State Transition Links
29. {
 "order": {
 "state" : "received",
 "..." : "...",
 "links" : [
 {"rel" : "cancel", "href" : "http://..."},
 {"rel" : "accept", "href" : "http://..."},
 {"rel" : "reject", "href" : "http://..."},
 ...
 ] }
 }
30. { 
 "rel": "search",
 "template": "http://example.com/search?q={query}" 
 } <form action='http://example.com/search' method='GET'>
 Search for: <input type='text' name='query'>
 <input type='submit'>
 </form >
31. {"target": "http://example.com/add",
 "rel": "add",
 "template": { 
 "first": "...",
 "last": "...",
 "bdate": "..."
 }
 } <form action='http://example.com/add' method='POST'>
 First: <input type='text' name='first'>
 Last: <input type='text' name='last'>
 Birthday: <input type='date' name='bdate'> <input type='submit'>
 </form >
32. Bene f its REST APIs Use for maximum evolvability and long- term needs •Loosest possible coupling •Dynamic affordances •Evolvability for new needs •Server-side logic •Generic semantics •Mature infrastructure
33. REST APIs Avoid for high-ef f iciency needs or in case of strong resistance Downsides •Harder to use (it’s not easy to be simple) •Requires consumer cooperation to succeed •Continuous justi f ication required
34. for people who can’t make up their minds GraphQL
35. GraphQL •Query and mutation language for graphs, tunneled via HTTP POST •(Recursive) selection of desired nodes and properties •Pagination •Subscriptions •Tool support for caching, of f line availability •Tooling for server-side bridging to existing APIs and databases •Native query syntax, JSON output
36. updateQuote() cancelSubscription() f indMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers() getOrderDetails() getNewOrderInfo()
37. getNewOrderInfo() updateQuote() cancelSubscription() f indMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers() getOrderDetails() Query Mutation Subscription
38. Bene f its GraphQL Use for accessing graph- based data in unforeseen ways •Ease of use (?) •Standardized query semantics •Data selection •Extensive tooling •Subscription support
39. GraphQL Avoid for server-centric logic, beware of SQL-on- steroids effect Downsides •Client-side logic •Tight coupling via data relationships •High server-side complexity •Risk of “Lipstick on a pig” effect •Clients can create performance issues
40. for speed, ef f iciency and sustainability 0-API
41. 0-API: Don’t do it •Martin Fowler’s f irst rule of distributed objects: Don’t distribute your objects •APIs take effort and create – don’t build them without good reasons •Consider non-remote APIs for internal applications •Consider Web-based UI integration for public offerings
42. Summary … but if you decide to build an API: •Consider GraphQL for special purposes •Pick (g)RPC or similar if the cost of coupling is worth it •Add some hypermedia to your HTTP APIs to make them RESTful
43. Krischerstr. 100 40789 Monheim +49 2173 3366-0 Ohlauer Str. 43 
 10999 Berlin 
 Ludwigstr. 180E 
 63067 Offenbach 
 Kreuzstr. 16 
 80331 München 
 Hermannstrasse 13 
 20095 Hamburg 
 Erftstr. 15-17 50672 Köln 
 Königstorgraben 11 90402 Nürnberg innoQ Deutschland GmbH www.innoq.com Thank you! Stefan Tilkov stefan.tilkov@innoq.com +49 170 471 2625 @stilkov
44. Distribution of logic Consumer Provider Data Business Logic Presentation
45. Distribution of logic Consumer Provider Data Business Logic Presentation