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
2. $$$ Making it easier to do business with you
3. Platform-agnostic Decoupled Microservices Managed independently Software half-life
5. Will it fit in my head?
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
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" } } }
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
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 :-)