Creating an API that is easy to use and maintain is difficult. Ask Hootsuite. They took some wrong turns at early stages and have made great strides since then so that they can offer an API that’s fast, easy-to-use and easy to maintain. David Zhang over at the Hootsuite blog explains what lessons the company has learned since the early days.
Hootsuite wasted a lot of time in the early on fixing bugs like 500 errors that just couldn’t be explained. They started with an API for just one customer with 5 endpoints. It was built in a hurry and so it wasn’t built according to RESTful patterns and was inconsistent across endpoints for things like field names and error messages. The team spent a lot of time putting these things right so that they could offer 30 endpoints to support messages, profiles, media and more.
From these early battles, the first lesson learned was: focus early on a consistent error schema. Hootsuite didn’t have clear guidelines on errors at the beginning. The result was that there were inconsistent messages and duplicated codes all over the place. This confused internal and external developers alike. The team realised it should make a consistent error protocol and stick to it.
Lesson two is: make sure your API docs are current and accurate. As well as enabling a smooth developer experience, this helps you rapidly prototype apps with the API for clients. Even better it can be used to make sure your API is correct. Hootsuite uses Swagger as its API doc generator. It provides code generation and the creation of SDKs on top. For API testing, the team uses Dredd, which will read your docs and then run your sample cases on the relevant endpoints.
The third lesson is: avoid fragmentation in your APIs. Initially when Hootsuite wanted to update its API in a way that wasn’t backwards compatible, it decided to create a whole new API to avoid annoying older clients. This meant maintaining two APIs, which became unmanageable. They were later merged but this resulted in a lot of technical debt which is still being dealt with. David suggests instead rapid prototyping with clients so that you only need to maintain one API.
The last lesson is: test in production. Often even top dev teams don’t test in production, assuming that the tests in the dev environment are enough. They’re often not. Hootsuite’s production tests helped catch some bugs that were missed at the development stage. If you don’t have time to write these tests yourself, David recommends Runscope, with which you can create production tests quickly through a GUI.