Planning Your API's Capabilities
Planning out your API's capabilities is one of the most important steps you can take to make sure you’re designing an API that developers will love to use. Surprisingly, while being one of the most crucial steps in API development, this step is usually rushed through by companies excited to generate a product map and start working on code.
Why is planning your API’s capabilities so important? In many ways, building an API is like building a house. You can say, “I want my house to look like this picture,” but without the blueprints, chances are it isn’t going to turn out exactly the way you had hoped.
It’s important that you create a solid foundation for your API, just as you would a house. You should understand what your API should be able to do, and how it will work. Otherwise, you may lock yourself into a poor design or worse—create an API that doesn’t meet your developers’ needs. If that happens, you’ll find yourself taking a lot more time and spending a lot more money to fix what you should have planned up front instead.
Before we get started writing code, as we plan our APIs, we need to take a step back and ask ourselves, Who will be using our API? Are we building your API for your application’s customers? For their business partners? For third party developers so that your platform can be extended upon?
Another question we have to ask as we plan an API is: Why would our users (as we identified them above) want to use our API? What benefit does it offer them? You might want to think about asking your potential users, “Which actions would you like to be able to accomplish through an API?” Doing this will help you guesswork and instead find out exactly what they are looking for and which actions they want to be able to take within your API, which will prove your API’s value.
A very important step in API planning is to list out the actions that you want the API to accomplish. Now that you know what your developers want to do, list out the actions. For this exercise, you should simply create categories (such as “Users” or “Messages”) and add actions to them based on what part of the application or object it will affect.
When planning an API, it’s crucial to not only make sure you are accounting for your developers’ needs, but also understand how the different resources within your API will need to work together. This will prevent you from having to rewrite code or try to move things around as you design and build your API.
An API’s interface is a contract, and as such cannot be constantly changing. Many developers are hardcoding resources and actions, and as such changing the resource name, moving it or changing the data properties can be detrimental to their application.
To make sure you’re designing your API well, and for best practices in understanding your API's capabilities, download the eBook Undisturbed REST: A Guide to Designing the Perfect API.
Next, learn more about RESTful APIs.