Most-Common Mistakes Developers Make During API Design

If you’re a developer, you already know that building an API is not an easy task at all. In order to build an API that works properly, you need to pay attention to dozens of different elements. Just ask any developer how hard and time-consuming this job really is. After the development process is finished, the app who will implement your API will be dependent on your work. Like in any job, there are some mistakes you can make without even noticing that could prevent you from delivering a great product.

Now, we are going to talk about those mistakes and shine a light on how you could prevent them from happening.

Mistake No.1: The users are not notified about the API changes

Maybe you are not considering the redesign of your API as something important. Well, you should. The changes to your API could force its users to make some changes to their applications or websites. Naturally, they need to be notified about this before it actually happens. Catching them off guard with this is not professional. In order to prevent this from happening, you need to inform the users about the changes in your API before they happen and provide some opt-ins for the users.

Mistake No.2: Adding new features before writing the documentation

If you are adding new features to an existing API, you need to consider how those features will fit in with the other ones. If you are not doing this, sooner or later, some problems are bound to emerge. Some of those problems could be very difficult and expensive to fix, especially if you API went public already. The solution to this problem is pretty simple. Have your REST documentation ready before you add some new features and release it to the public.

Mistake No.3: Giving the same rate limit to all users

This happens when your basic rate limit of RPHs (requests per hour) is too small and you have the consumers who are demanding more. The customers with bigger needs will spend all the calls quickly, and they will request an increase. Their application will be blocked until they can make some calls again. To avoid this problem, you should build flexible rate limits. Also, you could separate your expensive calls and the cheaper ones in separate rate limits.

Mistake No.4: Not providing insight into data and usage

Some of the users will probably be interested to know how many requests they can make in a certain period of time. They will probably want to know why some of their request failed. Some of the companies solved this issue by developing dashboards where all of the users can see every API request they made, the responses to their requests, etc. This dashboard should consist of all those information, and it should be used for exposing all the data and usage to consumers.

Mistake No.5: Ignoring task automation services

The task automation services should not be ignored. By using them you will connect you APIs much easier. Some teams of developers are choosing not to collaborate with task automation services. Eventually, they are forced to collaborate with them, because of all the work those services are providing to their API traffic. By partnering with task automation services, the integration options for your users are going to be expanded.

Mistake No.6: Ignoring the requests you mistake for duplicates

Of course, you shouldn`t accept the requests you are sure that are duplicates. By mistaking the valid requests for duplicates, you could lose some potential users. But how can you really know which ones are valid and which ones are not? There are ways to let the users define their uniqueness. One of those ways is the “idempotency key” that is passed by the user. When you accept the request for the first time, the result will be stored in cache memory. All of the requests made in the future with the same key will be served from the cache.


Like we said earlier, when building an API there are some elements you need to pay attention to. All of those elements are equally important for the proper working of your API. We gave you an insight into mistakes that are frequently made by developers.

Correcting some of these before the problems emerge could be crucial for the success of your product in the future. In addition, have in mind that users of your API are depending on you to be smart, and prevent all the thing that could overcomplicate their use of your API.

We hope you enjoyed while reading our article. If you have some questions or have something to add, just leave the comment and we will have the answer for you shortly. Thank you for reading our article.