5 Features of a Good API Architecture

Everyone is writing APIs—from microservices to full applications—but what makes a good one? Rob Allen outlines five of the more important architectural features that you should consider when designing and building your API, including developer-friendly features like thoughtful error handling and documentation. 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. Give your API a competitive edge by making sure developers want to work with yours rather than your competitors’.

Presented at O'Reilly Software Architecture, London on 20 October 2016

Transcript

1. 5 Features of a Good API Architecture Rob Allen 19ft.com ~ @akrabat ~ October 2016
2. Fit for Purpose Rob Allen ~ @akrabat
3. But first… Your target audience matters! Rob Allen ~ @akrabat
4. Features of a good API Malleability Correctness Client focus Documented Secure Rob Allen ~ @akrabat
5. A good API is malleable Rob Allen ~ @akrabat
6. Malleability • The representation is independent of the DB schema Rob Allen ~ @akrabat
7. It's about focus Different objectives • API is client focussed, DB schema is application focussed • Representation of data is different • Your API becomes brittle Rob Allen ~ @akrabat
8. Malleability • The representation is independent of the DB schema • Design is based on state changes Rob Allen ~ @akrabat
9. Workflows are more than CRUD • Operations are a series of steps • Think about goals and sequences of actions • Make it easy for a user to accomplish their tasks! Rob Allen ~ @akrabat
10. Malleability • The representation is independent of the DB schema • Design is based on state changes • Hypermedia aware Rob Allen ~ @akrabat
11. Hypermedia Hypermedia as the source of client flexibility! • Rename endpoints at will • Re-home endpoints on different servers (e.g. CDN resources) • API is explorable Rob Allen ~ @akrabat
12. A good API is correct Rob Allen ~ @akrabat
13. Correct • Media type format suits the design • Correct use of HTTP verbs • Understanding of Idempotency • Richardson Maturity Model 2+ Rob Allen ~ @akrabat
14. Media types matter With application/json you abdicate responsibility. The correct media type: • Tells the client how to interpret the data • Enforces structure of the payload • Informs on what the payload data means Rob Allen ~ @akrabat
15. HTTP verbs Method Used for Idempotent? GET Retrieve data Yes PUT Change data Yes DELETE Delete data Yes POST Change data No PATCH Update data No Rob Allen ~ @akrabat
16. Richardson Maturity Model source: http://martinfowler.com/articles/richardsonMaturityModel.html Rob Allen ~ @akrabat
17. A good API respects the client dev Rob Allen ~ @akrabat
18. Great error handling • Error representations are first class citizens • Honours accept header • Correct content-type • Uses correct HTTP status code • Provides application error code & human readable message • ideally in a known media type such as api-problem • Pretty print JSON for the humans! Rob Allen ~ @akrabat
19. Error messages • End user needs a short, descriptive message • Client developer needs detailed information • Client application needs an error code • The API application needs logs! Rob Allen ~ @akrabat
20. Error codes Send correct HTTP status code • 2xx for success • 4xx for failures the client can fix • 5xx for failures the client cannot fix Include an application error code • For the client application to parse Rob Allen ~ @akrabat
21. HTTP Problem (RFC 7807) 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 - try later.", "detail": "The authentication service is down for maintenance.", "instance": "https://example.com/maintenance-schedule/2016-08-30", "error_code": "AUTHSERVICE_UNAVAILABLE" } Rob Allen ~ @akrabat
22. Handling changes • Avoid major new versions • Make changes backwards-compatible • Think about forwards-compatibility Rob Allen ~ @akrabat
23. BC changes • Add resources • New verbs to existing resources • New endpoints • New format via content negotiation • Avoid change: New query arguments / new fields Rob Allen ~ @akrabat
24. A new version is a new API • Creates URL proliferation • Doesn't matter how you define it: • api.example.com/v2/user • api2.example.com/user • Use Server header for minor and patch info Rob Allen ~ @akrabat
25. Deprecation policy • Provide plenty of warning • Remove from test servers first • Communicate widely Rob Allen ~ @akrabat
26. A good API is documented Rob Allen ~ @akrabat
27. Documentation within the API • Content-type header • Link relations • Profile links • Structured data Rob Allen ~ @akrabat
28. Profile links Profile links provide the application semantics (RFC 6906) In the header: Link: Link: <https://www.example.com/docs>;rel="profile" Content-Type: application/hal+json;profile="https://www.example.com/docs" In the body: "_links": { "profile": { "href": "https://www.example.com/docs/" } } Rob Allen ~ @akrabat
29. Structured data There's no such thing as self-explanatory! {"christian": "Rob", "patronymic" : "Allen"} {"forename": "Rob", "surname" : "Allen"} {"firstname": "Rob", "lastname" : "Allen"} Rob Allen ~ @akrabat
30. Structured data There's no such thing as self-explanatory! {"christian": "Rob", "patronymic" : "Allen"} {"forename": "Rob", "surname" : "Allen"} {"firstname": "Rob", "lastname" : "Allen"} https://schema.org/Person: {"givenName" : "Rob", "familyName" : "Allen"} Rob Allen ~ @akrabat
31. Human documentation • Sensible URLs • Tutorials • Semantic information Rob Allen ~ @akrabat
32. Sensible URLs • The actual URL does not matter to the client API • It does matter to the client developer! GET /events GET /events?filter=upcoming GET /events/455dbab6 GET /events/455dbab6/talks GET /talks/6cf948e5 GET /talks/6cf948e5/comments Rob Allen ~ @akrabat
33. The for-human documentation • Tutorials to show how to use the API • Describe all the semantic information • Examples in multiple languages Rob Allen ~ @akrabat
34. A good API is secure Rob Allen ~ @akrabat
35. Security • SSL • Authentication • Rate limited Rob Allen ~ @akrabat
36. Authentication • HTTP Basic • OAuth2 Rob Allen ~ @akrabat
37. OAuth 2 • Requires an access token • More than one way to get a token: • Via username/password • Via API server • Tokens are short life with refresh token to get a new one Rob Allen ~ @akrabat
38. Rate limits Limit by application or user token Provide information HTTP 429 Too Many Requests X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4999 X-RateLimit-Reset: 1471549573 Rob Allen ~ @akrabat
39. To sum up Rob Allen ~ @akrabat
40. Thank you! Rob Allen ~ 19ft.com ~ @akrabat