5 Essential Rules on Working with Unstable APIs

In a distant land called Developer’s Heaven the sun shines bright (and doesn’t make your screen unreadable), the summer breeze tickles your face and there are beautiful APIs for you to grab from stable server trees.

Sounds dreamy, right? The reality of it is that we are here and we need to deal with the real world where the sun is not our friend and the APIs are often undocumented, unstable or even worse—not working at all. The situation I am talking about is highly probable with APIs being under development. The problem is you want to integrate with them but have no way to change them because it’s an external resource or you didn’t write the code behind it.

Here are some small, yet powerful tips to help you stay sane while at work.

• Write API mocks
  You probably won’t like what I am going to write but here it goes. You will most likely have to start with a mocked API because if you don’t, it will eventually come and hunt you down. In terms of an unstable API, or one that is under development, you will often be faced with a situation where it won’t be available for the whole day. Are you going to wait and waste your time? And imagine it is going to be e.g. 30% of your time. It is not easy to estimate the time it will actually take but if it happens the second time you try and you still don’t have a mocked version, you better get started on creating that right away!

• Keep the mocks DRY
  So you have your API mocked by commenting out parts of the HTML on your website and replacing it with some nice texts like Here be dragons. I am very sorry to inform you that this won’t work well. It is very hard to track all the instances of a hardcoded text or object, which is then populated to some child components.You should keep the mocks in as few places as possible and the best place to put them inside your project is one Class/file/module/component, or whatever you are working with currently so that:
  a) it doesn’t interfere with the production code
  b) can be easily turned off or removed.
  Trust me when I say, you will save yourself time and stress by keeping the mocks DRY.

• Make API address configurable
  You can combine this one with the previous point. If you are able to put the API on a different host so that turning it on or off is only a matter of changing the configuration for API endpoint base–that’s even better. The point is if you are using a real (unstable) API, you might be in a situation where the development API endpoint is down and you need to switch to another one temporarily. It’s also nice if the config file is ignored by git (or whatever other version control system) so that you won’t commit it by mistake.

• Install API cache package
  If the API is not being actively developed but there are situations when it’s down for a longer time period, you might try out one of the API caching packages. These packages are widely spread across popular technologies. For python, there is e.g. requests-cache and for node.js, there is apicache.One of our developers – Czarek, was once so frustrated he had to create node-api-cache-proxy. We are currently using the last one and our lives have become better since 🙂

• Double check the response structure
  It’s very hard to debug an error occurring after the API structure has changed on the server and your mock is actually working. The structure changes might not be visible at a glance and you might lose a lot of time trying to debug them. It’s better and faster to just check things more thoroughly so you will be able to catch the API errors more precisely. You will save yourself some time, which will leave you some time for having a coffee.. You might also consider using an API documentation tool like API Blueprint.

As you can see, it’s better to put forth effort to use these few simple practices so that you are less frustrated at work. By using API mocks or API cache, you can finally focus on the things you need to do instead of waiting around and wasting time. With this, you will finally feel a bit like you are in the Developer’s Heaven.