Building APIs that delight (Part I)

D02b5e0b9a348fa8d9bd2cac025eead3?s=47 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.

D02b5e0b9a348fa8d9bd2cac025eead3?s=128

Steven Ringo

February 14, 2014
Tweet

Transcript

  1. Building APIs that delight (Part I) 11 February 2014 Rorosyd

    Steven Ringo | stevenringo | steven@stevenringo.com
  2. $$$ Making it easier to do business with you

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

  4. None
  5. Will it fit in my head?

  6. None
  7. None
  8. None
  9. HTTPs RESTFUL

  10. RESTFUL = REST + STFU + LOL

  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.
  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.
  13. Affordances Easy discoverability of possible actions

  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
  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
  16. Plural vs singular?

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

  18. None
  19. None
  20. A little secret:
 
 I don’t want to know about

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

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

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

  24. /dogs/1482 /dogs/809608a0-92e1 /dogs/fido ✓ ~ ✗

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

  26. Representation

  27. { "invoices": [ { "invoiceId": "402892053e100406013e1024aaec00d7", "invoiceNumber": "INV00000091", "invoiceAmount": 801.73

    } ], "paymentId": "402892053e100406013e1024ab7c00e3", "amountCollected": 801.73, "success": true } Pay invoice/s
  28. { "payment": { "id": "402892053e100406013e1024ab7c00e3", "amount_collected": 801.73 }, "invoices": [

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

    "invoice": { "id": "402892053e100406013e1024aaec00d7", "number": "INV00000091", "amount": 801.73 } } ] } } Pay invoice/s
  30. One root JSON object Arrays of JSON primitives Echo changes

    Partial objects
  31. GET /convert?from=AUD&to=USD&amount=100 POST /convert { "convert": { "from": "AUD", "to":

    "USD", "amount": 100, "account": { "id": "184498321" } } }
  32. None
  33. Everything worked: 200 OK ! You did something wrong: 400

    Bad Request ! We did something wrong: 500 Internal Server Error
  34. 201 Created 304 Not Modified 404 Not Found 401 Unauthorized

    403 Forbidden
  35. None
  36. Talking all the API things

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

    load balancing documentation
  38. My big fat MF rails app

  39. See you next time :-)