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.

Transcript

1. Building APIs that delight
   (Part I)
   11 February 2014
   Rorosyd
   Steven Ringo | stevenringo | steven@stevenringo.com
   

   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