Things to consider when choosing a third-party API

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.

Documentation

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.

• What’s the data format (JSON, XML etc.)?
• Which authentication mechanism is required (basic auth, API token, etc.)?
• How are successes and errors rendered?
• Which and how many calls do I need to complete my task?
• For inputs and outputs, which attributes are required? Which type should they be, what do they mean and are they any examples?
• If there are any string values with a specific format such as date, time, and country, then, which convention do they follow?

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.

Libraries

Having an SDK to consume an API can save you a lot of time, but be cautious about them.

• Is the SDK available in your language?
• Does it follow the latest API version?
• Does it handle all the features you want?
• Does it provide useful feedback for errors?
• Does it have any dependencies? Are they up-to-date? Beware that they might conflict with yours.
• What size is it? For example, this can be a red flag for mobile apps: you don’t want to double the size of your app, just because of a third-party SDK.
• If it has not been written by the company providing the API, be sure it’s mature enough and well maintained. Have a look at open issues, too.

Consistency

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.

• If it’s a REST API, make sure it follows the principles.
• If the output is formatted in JSON, make sure all outputs are in JSON - even errors.
• Check the cases of attributes (ex: Snake case, Camel case), and make sure all endpoints follow the same.
• Does the naming of endpoints and attributes/parameters make sense to you?

Support

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.

• Does your pricing plan include any phone support?
• If there’s phone support, is it available 24/7? If not, is it compatible with your time zone?
• If there’s no phone support, do they answer mail quickly?
• Are the answers relevant?
• Are there any community forums? Are they active?
• Does a status page exist? Are outages frequent, and if so, are they well explained?

Reputation

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.

• Can you find any resources on the internet aside from the provider’s page?
• Do the articles about the service tend to be negative or positive?
• Is it used by well-known companies?

Pricing

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.

• Is the price per month or per requests?
• If it’s per request:
  • What’s the request limit? Does it fit your expected usage?
  • How much are you charged per additional request?
  • Can you monitor usage?
• How many calls are you allowed to make per hour/day/month? It can differ depending on the plan.
• If there’s phone support, make sure it’s included in your plan.
• If there’s a free plan, don’t hesitate to try it before you pay for it.

Data privacy

Whether you are concerned by the GDPR or not, if any personal data transits between your service and the provider, you should have a look at the data privacy policy.

• Does it have a privacy policy page?
• For how long will they keep your data on their servers?
• Will your data be shared with third parties?
• If they provide an SDK, does it have dependencies on tracking libraries? If this SDK is implemented on the client side, it means that you need to ensure no data that can be used to identify a person is given.
• Is communication between you and the provider secured enough? Take a look at authentication and communication protocol.

Maintenance

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.

• Encapsulate all the provider’s related code in abstraction layers (Ex: Remove the company reference from the method names).
• Remove any provider’s related naming from your table/column names.
• If you have some extra time, add multi-provider support, to do a progressive migration or fallback support.
  • For example, if you have to integrate a push notification service’s API, design your system so it can support having two providers at the same time.

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.