5 Features of a Good API

Everyone is writing APIs from micro-services through to full applications, but what makes a good one? In this session we’ll look at five of the more important features that you should think about when creating an API. These are the features that ensure that your API plays well with HTTP and, more importantly, make your API a delight to maintain and work with. I want you to ensure that your API is a good HTTP citizen, while also providing developer-friendly features like thought

Presented at TopConf, Tallinn

Transcript

1. 5 F E AT U R E S O F A G O O D A P I R O B A L L E N N I N E T E E N F E E T LT D @ a k r a b a t
2. F I T F O R P U R P O S E
3. F E AT U R E S O F A G O O D A P I • Malleability • Correctness • Error handling • Documentation • Security @ a k r a b a t
4. M A L L E A B L E A G O O D A P I I S
5. D E C O U P L E Y O U R R E P R E S E N TAT I O N @ a k r a b a t
6. H Y P E R M E D I A • An explorable API • Rename end points at will • Re-home end points on different servers @ a k r a b a t
7. H Y P E R M E D I A { "_links": { "self": { "href": “https://api.example.com/orders/523” }, "customer": { "href": “https://api.example.com/customers/32” }, "invoice": { "href": “https://api.example.com/invoices/873” }, "shippingNote": { "href": “https://cdn.example.com/ad8wd4.pdf”, "type": “application/pdf” } }, "currency": “GBP", "status": “shipped", "total": 123.45 } @ a k r a b a t
8. C O R R E C T A G O O D A P I I S
9. E M B R A C E H T T P V E R B S METHOD USED FOR IDEMPOTENT? GET Retrieve data Yes PUT Change data Yes DELETE Delete data Yes PATCH Update data No POST Change data No @ a k r a b a t
10. S TAT U S C O D E S M AT T E R 1xx Informational 2xx Success 3xx Redirection 4xx Client error 5xx Server error @ a k r a b a t
11. M E D I A T Y P E S • Read Content-Type header to decode incoming data • Honour the Accept header when sending data @ a k r a b a t
12. G R E AT E R R O R S A G O O D A P I H A S
13. G R E AT E R R O R H A N D L I N G • Error representations are first class citizens • Code for computers; messages for humans • Pretty print for the humans! @ a k r a b a t
14. H T T P P R O B L E M ( R F C 7 8 0 7 ) HTTP/1.1 503 Service Unavailable Content-Type: application/problem+json Content-Language: en { "status": 503, "type": "https://example.com/service-unavailable", "title": "Could not authorise user due to an internal problem.”, "detail": "The authentication service is down for maintenance.”, "instance": “https://example.com/maintenance-schedule/2017-06", "error_code": "AUTHSERVICE_UNAVAILABLE" } @ a k r a b a t
15. D O C U M E N T E D A G O O D A P I I S
16. P R O F I L E L I N K S ( R F C 6 9 0 6 ) Header: Link: <https://www.example.com/docs>;rel="profile" Body: { "_links": { "profile": { "href": “https://www.example.com/docs/" } } } @ a k r a b a t
17. H U M A N D O C U M E N TAT I O N • Tutorials • Reference @ a k r a b a t
18. S E C U R E A G O O D A P I I S
19. O A U T H 2 • Application identification • User identification • User’s trust relationship is with the API @ a k r a b a t
20. R AT E L I M I T HTTP/1.1 429 Too Many Requests Content-Type: application/problem+json X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1471549573 { "status": 429, "type": “https://dev.example.com/rate_limits", "title": "API rate limited exceeded.”, "error_code": "RATE_LIMIT_EXCEEDED" } @ a k r a b a t
21. T O S U M U P
22. @ a k r a b a t R O B A L L E N T H A N K Y O U