• Home
  • Five basic things developers do wrong when building API

Five basic things developers do wrong when building API


First thing that is important, when making API and what developers often forget, is versioning.

Why is versioning important?

Well, let’s consider this: You have built your application around some API and of course now you are heavily depend on it. Consider that you have your methods that fetches some JSON from path that you have as constant in your code, and other methods that parse that JSON the way you need it. So, what happens when API developers decide that they will change everything and make new version of their API.

If they did their job right, you wouldn’t notice anything. Why? Because they will not change a single thing on version of API you are using.

Let’s say you are fetching some API data from this url:


If they changed anything they don’t mess with this path, but instead make a new version and push breaking changes there. Now url will look something like this:


This way you can still use old API version and you get to decide when to switch to the newer one, only when you make all required changes, so that your application continue to work normally. Always have API versioning included. Even though this is basic thing, I come across APIs that do not have it, on regular basis. Do not do the same mistakes as they did.

API Documentation

This is something that I know a lot of developers do not want to do, but it is part of their job. By not having good documentation, you are undermining all good code you wrote, because no one is going to know how to use your API.

Write documentation with the goal of not get any support tickets or emails. If you ever get ticket or email with some questions that means that you are missing some documentation part and that you should immediately update it and add whatever your customer has just asked you to. Yes, even if that question is something stupid (of course there are stupid questions ). If some question doesn’t belong to any category of your documentation and you do not know in which section to put it, just have FAQ section in your document in which you can put all inputs you get from clients and customers.

Also, by having good documentation you are seen as very competent and professional, and your service that you provide will be more successful and trustworthy.

HTTP Status Codes

This one is a bit controversial, but let us get it out there.

It is wrong to return HTTP Status Code 200 (OK) with error message as a response. HTTP Status codes tell application how to react to request. So if we return code that says that everything went OK, even if we have just had an error, it means that we are not using HTTP the way it is intended to be used.

I know that some of you will say that HTTP status codes have nothing to do with business logic of API and technically request is OK, there were no errors on server or request was not bad. Nevertheless, you should know that HTTP is an application protocol, and HTTP status codes should reflect that. Also this by not using HTTP code as they are intended to be used, you are breaking REST, as 2xx is considered to contain response that have that resource as return object. So if we are not getting resource back and instead we are getting error response, you cannot have 2xx HTTP status code.

Testing Environment

Consider you are doing an integration of your service with some API. Let us say that it is payment system. Therefore you would have to test everything twice before releasing it to the production, because we are dealing with people’s money, so we want to be double sure everything works as intended. There is a big list of all the things that can go wrong, but you have no way to testing that.

Let’s say this there are 4 scenarios for payment result:

  • Payment can be successful
  • Payment can be refused ( for different reasons each of which have unique code and message )
  • Request is bad ( unsupported currency, invalid amount, etc…)
  • Fraud detected on Credit Card

We can test three out of this four scenarios. Our API provider did not prepare fraud detection scenario. We can never get that error message, response is different and different parsing and actions need to be done. Because of this reason, we now have untested integration.

So when you are building an API, always consider to be client friendly and implement test service that will cover all possible scenarios.

In our example that would be simply solvable by having dedicated number of a test card, so we client sends the request for payment with that card, it would respond with fraud detection error.


By consistency I mean two things.

First thing is not to mix return types for different API endpoints. I had “pleasure” of integrating system that had authorization using SOAP and the rest was done in JSON. Why would you do that? Would you want somebody to do that to you? No? Then do not do that. Be consistent. It is not a problem to have entire service in SOAP, just have everything in that one.

Second thing you should be consistent is to use property names consistently. Do not have property name api_key (underscore) in one endpoint and apiKey (camel case) in another. Just the other day we had one API use property merchantPassword in one request and then merchantPass in another. That sort of thing just shows that you are being lazy, inconsistent and unprofessional.

Do not be stupid on small things like consistency and lose your reputation as good API provider.

If you disagree with me or have something to add please leave a comment and I will try to respond to anyone that is in the mood to talk.

Also I am writing a book about Legacy Projects so if you want to check that out click here.

About the Author

Follow me

30 year old software developer from Mostar, Bosnia and Herzegovina, currently living and working in Frankfurt am Main, Germany.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}