One of the first questions I ask when a new app emerges is, “does it have an API?“.
The truth is:
A web application should not begin with UI design.
It should begin with an understanding of how the API will behave.
We live in a very interconnected world. The app you are building today is not going to live in a silo. People and other apps are going to need to interact with it outside of the UI.
This post by Tom-Preston Warner, one of the founders of GitHub, captures API first design:
A perfect implementation of the wrong specification is worthless. By the same principle a beautifully crafted library with no documentation is also damn near worthless. If your software solves the wrong problem or nobody can figure out how to use it, there’s something very bad going on.
Designing the API first ensures the right specification is implemented, and other developers will know how to interact with it.
What is API first design?
API first design is the act of documenting the API before it is implemented in code.
Note: If you want to modify code you should update the API documentation first before making the code change.
Why should you practice API first design?
Documenting the API before writing code enables greater collaboration and makes code improvements more cost-effective – it’s much easier to change documentation than working code.
What happens when you don’t design the API first?
A lot of maintenance work will be needed to make it ready for public consumption.
A few things you’d need to do:
- Make sure you aren’t leaking private data.
- Hide private methods.
- Version the API.
This work would take far less time if it was done up front while the application is being built.
Another benefit to having a well documented API is more customers.
Developers will often choose between competing products based on the quality of the API they will be interacting with.
How do you practice API first design?
One method that has been helpful for us on a recent project is to have a different developer for both consuming and developing the API.
Having someone use the API immediately as it is being developed provides valuable feedback you would’t think of while consuming it yourself.
There are many tools out there to write an API.
One tool is Swagger. It allows you to write API docs in an easy to read and write YAML format, and converts the docs to an interactive web page.
Whether you write an API doc in a simple text file, generate it from code, or use a tool like Swagger or API Blueprint, designing the API first will provide many functional and bottom-line benefits.