As M. Henning said, it is easy to create a bad API, and it is very hard to create a good one. The statistics show that more than 80% of software in the development process at the moment will fail to meet its deadline. And unfortunately, APIs are not an exception to this rule.
When you are developing an API, you can easily get lost in the development process without thinking about its future consumers. There are some mistakes that are often made along the way to API completion. So, now we are going to present you some tips that could help you in building your API.
1. Make Sure that the Documentation is in Order
Nobody likes to spend countless hours on documentation. It is boring and takes a lot of patience. But it is crucial because if you provide a good documentation for the consumers of your API, they will not have a hard time understanding how to use your API correctly. The documentation should be easy to understand. Some mistakes, you could potentially make in writing the docs, could produce some misunderstandings and confusion about the implementation and accessing the information in your API. You probably wouldn’t want to read a documentation that is not clear in its instructions.
2. The Authentication Must be Foolproof
Authenticating by using username and password is something that we are doing every day. Authentication in the world of APIs, is something that is needed for private APIs. On the server side, you could implement some support for the authentication into your API controllers. All of the HTTP clients, naturally, need to have some HTTP basic authentication implemented inside them. One more way is allowing the users to sign in by using some access tokens. For example, the tokens could be used in CI-server setups. By giving this tokens, you will share an access to your private data, but you will not reveal your password.
3. Think about Versioning Well in Advance
When you start the development of your API, version it. That is something you could do without sweating. If your API becomes successful in the future, you can just build on top of the old version and create a new version. This is important because editing an existing API is something really bad and really hard to do. Consumers of your API are counting on that existing interface. By counting we mean, they could have some very important business strategy that relies on your API. If you change your API without notifying the consumers and without their consent, that could end with lawsuit against your company.
4. Returning Error Messages
It is very important to always return error messages in the same format. By doing that, you will spare your consumers of dealing with different semantics on different resources. As you can see, dealing with the error in your API could sound pretty easy. However, you need to come up with a strategy for resolving these issues. Linking the part of your documentation that relates to the error and the certain error message could be the solution. Ask any developer, what is the worst thing that can happen while using other developer’s software. We guarantee that almost all of them will say “Error with no error message”.
5. Rate Limiting
You will not have this kind of problem in the beginning. If your application becomes popular and your API becomes widely used by other developers, some problems could emerge. Some of those developers could request the same URL more than a thousand times in some period of time. So you should implement a rate limit in your API as soon as you can. By doing this, you will prevent the crash of your server and you could get a recommendation of how much requests you should limit in some time interval.
Conclusion
In order to get the fruits of your API, you need to invest a large amount of time and thinking about what you could improve. Coming up with a strategy before and while building your API is crucial for its success. This is important because, after your API becomes popular and widely used, you won’t be able to make some changes in its principles without damaging some of your consumers. Reading this type of articles and coming up with the conclusions is something you could really benefit from. In the end, we just want to remind our readers of the sentence said by prominent Australian software engineer Michi Henning, which we mentioned at the beginning of this article.
We hope our article was informative and enjoyable for you. If you want to correct or ask us something, feel free to leave a comment down below. We will respond as soon as we can. Thank you for reading our article.
You may also like to read: API Collaboration Best Practices