Exposing an API has become a standard these days, as it makes integration much easier. Clients that integrate with your service may not be 3rd party entirely. It can be your website, mobile app or another service of yours which needs access to the data. Third party clients can range from your customers, in house apps, digital assistants or chatbots. When developers consciously develop an API with third party integrations in mind, they take time to design the request and response parameters to make it easy to understand and implement. But, if a developer starts with internal implementations in mind, in some instances, not enough attention is paid to the ease of integration. This happens because, the same team (or the same developer in some cases) owns both sides of the integration and is easy to communicate and implement. As the team grows and the product reach increases, it gets difficult for third party developers or other team members to understand and integrate. It is better to start with a third party developer when designing the interface, so that more attention is given to the ease of implementation. From our experience, following are some of the elements that a team should keep in mind when designing an API interface.
The consumer of an API always tries to maintain a standard parsing code, as the code is easier to manage rather than having multiple implementations. As an API provider, a developer should define a standard structure so that the consumer can design the data objects without much guessing. Adding a standard success state, especially at the root level will greatly improve the implementation logic.
We have seen this multiple times, where the error messages are nested in a complex object. It takes quite a bit of exploration to determine the response if the error message is not effectively communicated. It is a good practice to have an object dedicated for error messages, parallel to the success state.
Keep it lean and clean
It is always easy to do a data dump of the database as your never know which data field is required by the consumer. While it seems logical, it also comes with quite a bit of complexity. The consumer has to parse lot of data to pick and choose the parameters they require and also the call may consume quite a bit of network bandwidth. If the client is a mobile app, care should be taken not to consume their user’s data plan, all with a single app.
It is a given truth that all applications change over a period of time. It should also be understood that not everyone switches over to the new API version immediately. In case of mobile apps, various users have various versions as not everyone updates to the latest version immediately after the release. Moreover, device compatibility may not allow a user to upgrade. For these reasons, to account for backward compatibility, it is always suggested to version the API.
It is an undisputed statement that every piece of software should have some kind of documentation. With API, it will be impossible for someone to understand the request and response without documentation. The client could be on the other side of the planet, in a different timezone, which could make it time consuming to explain the structure. A simple web page will make implementation a breeze.
Who doesn’t like free samples? Might it be a supermarket or a software, a sample will greatly help in the implementation and will answer many questions. Data types, formats, length of a value etc could easily be communicated with the help of documentation and providing sample request and response.
While most of the developers follow this, it is important to mention environments, when we are discussing API best practices. Environments will allow the client to test the services without worrying about the implications. If you can provide access to logs and such, it will help in making integration easier and minimize email communication, greatly improving the speed of implementation.
We have experienced the pain of integrating an API and came across all the above in varying intensity. To make it easier, we communicate a lot with the API developer and make sure the above issues are addressed. Did you come across any other issues that could make integration painful? Share your thoughts on our Facebook page or Tweet to us. We will also be glad if you plan to send us an email to email@example.com and share your perspective.