August 26, 2019

API Design 101

APIs are the new user interfaces. And just like we put a lot of effort into UI/UX, we need to make sure our APIs are easy to use and makes sense, so that developers can easily consume it. They should be so easy to understand and use, to allow developers the follow the 5/5/5 rule:

  • developers can understand what an API does in under 5 seconds
  • developers can get a hello world going in under 5 minutes
  • developers can have the API used in production in under 5 days

This post will serve as a very quick listing of resources and links to start with when designing and building APIs:

At WeWork, we use JSON Schema to describe the data models, OpenAPI to describe everything else, then the message being described is usually JSON API.

API Tools

A really big announcement for API Design is about Stoplight Studio, which I have started using it.

The API tooling eco-system is building up nicely. Here is list I made last year some time ago (on confluence, so just pasting the image below)

See this for API documentation:

API Lifecycle and tooling:

  • Apiary for documentation
  • Dredd for validation
  • Runscope for testing
  • Jenkins for automation

There is a bunch of REST tooling floating around that’s not awful

And to close it off, let me list some of the design choices we have made in the last few months. This was our first attempt at building APIs, and I think we did OK, for a first time. There are definitely some things I would change the next time.

  • We use a 'data' envelope
  • We use HATEOS links

"data": {
"_links": {
"self": {
"href": "https://..... "

  • Both made sense at the time. We wanted HATEOS links, so we needed an overall envelope. I kinda regret the HATEOS links now - I think its bulky, and APIs are not yet like the web, where you can navigate using links.
  • We used OpenAPI v2 (swagger) to describe the spec.
  • We kinda made our own error objects. We should have used RFC 7807 or JSON API