External third-party-services APIs are useful: they allow you to benefit from the expertise and knowledge that others have acquired on a specific subject - a subject which is not your area of expertise and not the problem in hand. It would take too much time and effort to build and maintain such a service yourself.
However, choosing an API isn’t always an easy task.
Indeed, your choice will have an impact on your codebase and database architecture, and even your service itself. Imagine if your third-party payment-service went down: your customers wouldn’t be able to buy your products.
There are a lot of services that are alike providing APIs, with similar pricing and features.
So, how can you be sure you are making the right choice?
I’ll try to list all the different questions you need to ask yourself before implementing an API, covering documentation, libraries/SDKs, support, pricing, data privacy, and maintenance.
Most of the time, when you need to choose a third-party library and there’s no documentation available, you can have a look at the source code to understand how it works and evaluate the code quality.
For a third-party-service API, as you won’t have access to the source code, you need to find a way to understand how it works, and to evaluate the implementation complexity.
Proper documentation should give you an idea of how your implementation looks. Most of your questions should be answered.
Some documentation also provides live querying tools, enabling you to run tests to ensure documentation and code are aligned. If it does not, be sure to find a way to test it before implementing it, because you can find some significant differences between documentation and production APIs.
Having an SDK to consume an API can save you a lot of time, but be cautious about them.
While you’re having a look at documentation and the library, make sure everything is consistent. Lack of consistency can mean the underlying code quality is poor, and you’ll have trouble implementing it.
Technical support can help a lot when you need your questions answered, whether it’s for implementation questions, or when you think there’s an outage.
Doing some research on the Internet can help you avoid surprises: find out the frequency of breaking changes and outages, or get news about the selling of the company providing the service and save yourself a migration.
This is a tough one because when you compare API pricing, you could think one is cheaper than the others. However, digging deeper can make you realize the cheaper one is actually more expensive on higher volumes.
For a start, look beyond the pricing plan that suits your needs: you’ll scale eventually, and you’ll quickly realize that adding a new user or making a few extra requests will become so expensive that you’ll need to migrate to another service anyway.
Even if all the lights are green and you are confident with your choice, have in mind that the third-party API you are integrating will be replaced eventually.
To ease up the replacement, design your integration with the migration process in mind.
To sum up, this is by no means an exhaustive list of the problems you might encounter when integrating third-party services. Spoiler: APIs are always tricky. This article feeds off our own experiences and struggles. It explores the trade-offs to be made, between investing time and energy in building and maintaining a service yourself, or choosing to benefit from the expertise and knowledge of a third-party service when you integrate their API - warts and all.