Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Approaches: An Overview

API Approaches: An Overview

A brief look at the most popular approaches for APIs

Afd6dc452bc20f8f06612d4792bb8be3?s=128

Stefan Tilkov

June 16, 2021
Tweet

More Decks by Stefan Tilkov

Other Decks in Technology

Transcript

  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