Let's Build an API together - Part 6

Last Update: 20.12.2017. By Jens in API Series | APIs | Newsletter

Now that we have covered the essentials, we could go and hack our MVP together. However, we will look at other options first.

When we start out, we have basically two ways here:

1. We dive into code and build the API
2. We design the API first

We all know and have done the first one. And it is a valid approach, although, for the series, we will go the second way :-) But fear not, we are not going to draw any UML diagrams or alike. There are more coder-friendly options.

In recent years a few specifications emerged around designing and also documenting an API, mainly in the REST space. I’ve written some overview articles about the specs on the blog, use this as an entry point. The interesting thing is they can also be used for a design-first approach. Essentially, we define our API in a particular syntax and can generate mocks, docs, test specs or even code from that. Seems it might have some benefits.

The candidates:

• API Blueprint is based on Markdown
• RAML is based on YAML
• OpenAPI aka Swagger is based on JSON or JSON as YAML

The all seem mature enough for production use, so I think it is just a matter of preferences. I’ll use API Blueprint for our Kanban API as I have never used it before. Although you can pick another one if you like.