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

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

    View full-size slide

  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.
    !

    View full-size slide

  3. Overview of API styles
    •(g)RPC


    •HTTP Web APIs


    •Hypermedia REST APIs


    •GraphQL


    •0-API


    View full-size slide

  4. a.k.a. CORBA’s cooler grandkid
    gRPC

    View full-size slide

  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

    View full-size slide

  6. Remote Procedure Call (in general)
    Interface Description
    Logical Communication
    IDL Compiler
    Client Server
    Lib
    Physical Communication
    Lib (De-)Serialization
    Skel
    Stub
    (De-)Serialization

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  11. like REST, but not really
    HTTP Web APIs

    View full-size slide

  12. updateQuote()
    cancelSubscription()
    f
    indMatchingBid()
    initiateProcess()
    submitApplicationData()
    listAuctions()
    getUsers()
    getOrderDetails()

    View full-size slide

  13. updateQuote() cancelSubscription()
    f
    indMatchingBid()
    initiateProcess()
    submitApplicationData()
    listAuctions()
    getUsers()
    getOrderDetails()
    GET
    PUT
    POST
    DELETE

    View full-size slide

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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  19. a.k.a. REST APIs
    Hypermedia REST APIs

    View full-size slide

  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, …

    View full-size slide

  21. How to turn an HTTP API into a REST API

    in 3 easy steps

    View full-size slide

  22. Step 1: Service Documents

    View full-size slide













  23. { "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/" }

    ]

    }

    }

    View full-size slide

  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/

    View full-size slide

  25. Step 2: Resource Links

    View full-size slide

  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"},

    ...

    ]

    }

    }

    View full-size slide

  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

    View full-size slide

  28. Step 3: State Transition Links

    View full-size slide

  29. {

    "order": {

    "state" : "received",

    "..." : "...",

    "links" : [

    {"rel" : "cancel", "href" : "http://..."},

    {"rel" : "accept", "href" : "http://..."},

    {"rel" : "reject", "href" : "http://..."},

    ...

    ]

    }

    }

    View full-size slide

  30. { 

    "rel": "search",

    "template": "http://example.com/search?q={query}" 

    }


    Search for: 


    >

    View full-size slide

  31. {"target": "http://example.com/add",

    "rel": "add",

    "template": { 

    "first": "...",

    "last": "...",

    "bdate": "..."

    }

    }

    First: 

    Last: 

    Birthday:


    >

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  34. for people who can’t make up their minds
    GraphQL

    View full-size slide

  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


    View full-size slide

  36. updateQuote()
    cancelSubscription()
    f
    indMatchingBid()
    initiateProcess()
    submitApplicationData()
    listAuctions()
    getUsers()
    getOrderDetails()
    getNewOrderInfo()

    View full-size slide

  37. getNewOrderInfo()
    updateQuote()
    cancelSubscription()
    f
    indMatchingBid()
    initiateProcess()
    submitApplicationData()
    listAuctions()
    getUsers()
    getOrderDetails()
    Query Mutation
    Subscription

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  40. for speed, ef
    f
    iciency and sustainability
    0-API

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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


    [email protected]


    +49 170 471 2625


    @stilkov

    View full-size slide

  44. Distribution of logic
    Consumer
    Provider
    Data
    Business Logic
    Presentation

    View full-size slide

  45. Distribution of logic
    Consumer
    Provider
    Data
    Business Logic
    Presentation

    View full-size slide