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:

• Start with the basics of REST and the Richardson Maturity Model
• Best Practices for Designing a Pragmatic RESTful API
• The book Build APIs You Wont Hate
• Other good articles by Phil, specifically REST and Hypermedia and
• JSON API, OpenAPI and JSON Schema Working in Harmony

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.

• Slack group for APIs You Wont Hate to chat to other API devs and designers
• Tool to start designing OpenAPI specs
• What is an API Platform?
• Tyk - Free hosted API Management Platform
• API Evangelist blog
• API University
• Nordic APIs

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

• API Platform
• Apigility
• Flask-Potion
• Fusio
• Go has a bunch of frameworks
• Silkapp
• VertX
• jsonapi-rb

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