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

Building APIs that delight (Part I)

Steven Ringo
February 14, 2014

Building APIs that delight (Part I)

An overview of building APIs in Ruby, Rails and related. Looking at REST, API design, tooling, documentation and practices.

Steven Ringo

February 14, 2014
Tweet

More Decks by Steven Ringo

Other Decks in Technology

Transcript

  1. Building APIs that delight
    (Part I)
    11 February 2014
    Rorosyd
    Steven Ringo | stevenringo | [email protected]

    View Slide

  2. $$$
    Making it easier
    to do business with you

    View Slide

  3. Platform-agnostic
    Decoupled
    Microservices
    Managed independently
    Software half-life

    View Slide

  4. View Slide

  5. Will it fit in my head?

    View Slide

  6. View Slide

  7. View Slide

  8. View Slide

  9. HTTPs
    RESTFUL

    View Slide

  10. RESTFUL = REST + STFU + LOL

    View Slide

  11. A RESTifarian is a zealous proponent of the REST software
    architectural style as defined by Roy T. Fielding in Chapter
    5 of his PhD. dissertation at UC Irvine. You can find
    RESTifarians in the wild on the REST-discuss mailing list.
    But be careful, RESTifarians can be extremely meticulous
    when discussing the finer points of REST.

    View Slide

  12. A RESTifarian is a zealous proponent of the REST software
    architectural style as defined by Roy T. Fielding in Chapter
    5 of his PhD. dissertation at UC Irvine. You can find
    RESTifarians in the wild on the REST-discuss mailing list.
    But be careful, RESTifarians can be extremely meticulous
    when discussing the finer points of REST.

    View Slide

  13. Affordances
    Easy discoverability of possible actions

    View Slide

  14. Resource POST
    create
    GET
    read
    PUT / PATCH
    update*
    DELETE
    delete
    /dogs Create a new
    dog
    List dogs Bulk update
    dogs
    Delete all
    dogs
    /dogs/fido Show Fido Edit Fido Delete Fido

    View Slide

  15. Keep URLs simple and intuitive
    Avoid verbs*
    Keep to two base URLs per resource.
    Keep verbs out of your base URLs
    Use HTTP verbs on collections and elements

    View Slide

  16. Plural vs singular?

    View Slide

  17. Nouns?
    calculate, translate, convert, subscribe, deploy*
    *so-called non-resources

    View Slide

  18. View Slide

  19. View Slide

  20. A little secret:


    I don’t want to
    know about your
    persistence

    View Slide

  21. /dogs/1482
    /dogs/809608a0-92e1
    /dogs/fido

    View Slide

  22. /dogs/1482
    /dogs/809608a0-92e1
    /dogs/fido

    View Slide

  23. /dogs/1482
    /dogs/809608a0-92e1
    /dogs/fido
    ~

    View Slide

  24. /dogs/1482
    /dogs/809608a0-92e1
    /dogs/fido

    ~

    View Slide

  25. /vet/pittwater/dogs/fido
    /vet/7e9d37f0-92b7/dogs/ef6a43d3-cd7b

    View Slide

  26. Representation

    View Slide

  27. {
    "invoices": [
    {
    "invoiceId": "402892053e100406013e1024aaec00d7",
    "invoiceNumber": "INV00000091",
    "invoiceAmount": 801.73
    }
    ],
    "paymentId": "402892053e100406013e1024ab7c00e3",
    "amountCollected": 801.73,
    "success": true
    }
    Pay invoice/s

    View Slide

  28. {
    "payment": {
    "id": "402892053e100406013e1024ab7c00e3",
    "amount_collected": 801.73
    },
    "invoices": [
    {
    "invoice": {
    "id": "402892053e100406013e1024aaec00d7",
    "number": "INV00000091",
    "amount": 801.73
    }
    }
    ]
    }
    Pay invoice/s

    View Slide

  29. {
    “invoice_payment": {
    "id": "402892053e100406013e1024ab7c00e3",
    "amount_collected": 801.73,
    "invoices": [
    {
    "invoice": {
    "id": "402892053e100406013e1024aaec00d7",
    "number": "INV00000091",
    "amount": 801.73
    }
    }
    ]
    }
    }
    Pay invoice/s

    View Slide

  30. One root JSON object
    Arrays of JSON primitives
    Echo changes
    Partial objects

    View Slide

  31. GET /convert?from=AUD&to=USD&amount=100
    POST /convert
    {
    "convert": {
    "from": "AUD",
    "to": "USD",
    "amount": 100,
    "account": {
    "id": "184498321"
    }
    }
    }

    View Slide

  32. View Slide

  33. Everything worked:
    200 OK
    !
    You did something wrong:
    400 Bad Request
    !
    We did something wrong:
    500 Internal Server Error

    View Slide

  34. 201 Created
    304 Not Modified
    404 Not Found
    401 Unauthorized
    403 Forbidden

    View Slide

  35. View Slide

  36. Talking all the API things

    View Slide

  37. SDKs
    testing
    tooling
    metrics
    caching
    versioning
    rate-limiting
    deployment
    authorisation
    authentication
    load balancing
    documentation

    View Slide

  38. My big fat MF rails app

    View Slide

  39. See you next time :-)

    View Slide