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 go back to the basics and look at what I consider to be five of the more important architectural 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 thoughtful error handling and documentation.

This presentation was given at RestFest UK.

Transcript

1. 5 Features of a Good API Architecture Rob Allen 19ft.com ~ @akrabat ~ July 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. Malleable • The representation is independent of the DB schema • Design is based on state changes • Hypermedia aware Rob Allen ~ @akrabat
7. A good API is correct Rob Allen ~ @akrabat
8. Correct • Media type format suits the design • Correct use of HTTP verbs • Understanding of Idempotency • Richardson Maturity Model 2+ Rob Allen ~ @akrabat
9. A good API respects the client dev Rob Allen ~ @akrabat
10. 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 Rob Allen ~ @akrabat
11. BC break policy • A new version is a new API • Has a deprecation policy Rob Allen ~ @akrabat
12. A good API is documented Rob Allen ~ @akrabat
13. Machine-discoverable docs • Profile links • Structured data • Scheme.org • ALPS.io Rob Allen ~ @akrabat
14. Human documentation • Sensible URLs • There's less of it! • Tutorials • Semantic information Rob Allen ~ @akrabat
15. A good API is secure Rob Allen ~ @akrabat
16. Security • SSL • Authenticated • Rate limited • Has a sandbox Rob Allen ~ @akrabat
17. To sum up Rob Allen ~ @akrabat
18. Thank you! Rob Allen ~ 19ft.com ~ @akrabat