API Design WorkFlow

Workflow that helps you develop an API that your end users want

API design workflow

API are the interface to your app so that any developer can easily extend and use your service. While building an API following things is a must to consider.

  1. Consistency
  2. Usability
  3. Security
  4. Documentation

We are designing API for the end user, so that they can easily integrate with our system. An API should be consistent across all end point. The response request format should always be made consistent.

An API must be granular but should meet the requirement of all the clients. The only way to know if it is usable, is by using it. But we don’t want to keep changing the source code with each feedback user gives us. This requires a lot of development effort.

Finally while using an API, it should be well documented so that it’s functionality is well known.

To achieve all these we need to have a good workflow setup. So that the users can see the documentation, use the api, and give feedback if any change needed.

A workflow for building a good API consists of following steps:

  1. Design
  2. Share
  3. Develop
  4. Test

For this workflow use any one of the standard for api design. There are lots of standard for this. You can choose any one from Swagger(Open API Specification), API blueprint, RAML.

The first step of the workflow is to design. Use the standard specification to design the API.

Sample specification for an API written in RAML [Image Source: http://raml.org/]

Once the API is designed share it with the end users. Collect feedback from them. The end users can actually use a mock server that is generated automatically from the specification you have written. This helps the users to actually try out the API without you needed to build the API. This helps to remove the development effort needed before the feedback of user.

Once you get feedback modify the API specification according to the feedback. After the modification and when the API is usable, you can now start to develop the API, based on the specification.

There are modular approach in writing the API specification. This helps to maintain consistency across different APIs you build.

Finally the documentation of API. The specification you just wrote can now be mapped into a UI of documentation, which can be used by the users to get information about how to use your API. Also there are tools like dredd that can automatically test if the documentation is according to the API or not.

This workflow is all about focusing on the need of the API consumer and also being able to maintain the consistency. A good workflow for a good API.