5 features of a good API

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.


Rob Allen

July 16, 2016


  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 ~

  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