Today, there are many tools that developers can use to create an API, meaning that some of them can come up with an API within a matter of minutes. However, there is a vast difference between just creating an API and building one that meets all your expectations, is reliable and secure. Some developers create APIs that work well but forget some basic things that, within no time, bring a lot of issues to the API users. In this article, we are going to talk about the basic mistakes that developers make when creating APIs.
Image Source: https://www.pexels.com/photo/photography-of-person-typing-1181675/
API Documentation
This is part of a developer’s job, but most of them are not happy with writing API documentation. However, what they do not know is that the lack of documentation only serves to undermine the excellent work they have done when they create an API. API documentation should be written with its goal being to minimize or avoid completely supporting tickets from the API users. Getting support tickets means that your documentation is not complete and that you should update it to prevent such questions in the future. Furthermore, proper documentation portrays a developer as a competent professional who knows what they are doing, something that might attract more customers for your API.
API Versioning
API versioning is one of the essential things that developers tend to forget. For example, let us assume that you have developed your application heavily relying on a particular API. You have methods fetching some JSON from a constant path in your code with other methods parsing that JSON just the way you need it. Then within a few months of your application running smoothly, the API developers decide to change everything to create a new version of the API. If the API developers had versioning implemented, you will not notice anything they are doing since they will not touch anything on the release of the API you are using. This way, you will be able to keep using the old version of the API. You can decide whether to change to the newer version or not. However, if they do not implement versioning, your application will break down.
Consistency
It is very important to make sure that your code is consistent. For example, there are developers that mix return types for different API endpoints. For instance, what would you feel using a system whose authorization uses SOAP, and the rest is done in JSON? If you are using SOAP, then there would be no problem at all using the same throughout the entire service. You also need to use consistent property names. For example, it is wrong to have property name myName in one endpoint then my_Name in another. This inconsistency shows how unprofessional a developer is.
HTTP Status Codes
HTTP Status codes are used to tell an application how to react when a request is made. This means that returning a code that indicates that everything is okay even when there is a single error is wrong. Furthermore, you will be breaking REST if you use HTTP codes the way they are not supposed to be used. This is because REST now contains responses that have a resource as a return object.
Finally, when creating an API, try as much as possible to implement all the test scenarios that will cover everything that your clients will use the API for. Some developers leave a required test case meaning that the API will never return an error is such a scenario. Avoiding these mistakes will help any developer design great APIs that run smoothly and that do exactly what they are supposed to do.
