Application Programming Interfaces (APIs) are extremely useful to developers. They allow 2 applications to communicate with each other, and in doing so they also allow developers ease of integration and the ability to automate tasks.
They allow us to gain from the skills and expertise that others have mastered in various subjects to create and maintain these services, and save us lots of time and effort in the process.
Sounds super straightforward, right? Just pick one of the available APIs and you have your work cut out for you. Well, as I learnt, choosing an API isn't always an easy task, as not all APIs are created equal. I found myself having to switch APIs mid-project and faced some serious challenges along the way, learning some valuable lessons in the process.
So, how do you go about choosing the right API for your project?
Here are a few key things one should take into consideration:
1. Documentation
Documentation is the #1 factor to consider when choosing an API. A good API should provide comprehensive documentation, preferably with FAQs. Evaluate it in detail first. It should also provide clear and useful examples. This sample code gives a glimpse into how implementation would look like.
2. Data Format
Once upon a time, XML was the dominant programmatic request data format. Since then, JSON, based on JavaScript, has emerged as a much lighter and easier-to-use alternative.
This is because unlike XML, JSON’s syntax is very close to most programming languages, thus making it very easy to parse it in almost any language. Moreover, JSON is also really easy to create. It is considered best practice to use JSON with REST.
In addition to the format, consistency is also a crucial factor. If it’s a REST API, make sure it follows the principles. Similarly, if the output is formatted in JSON, all outputs should be in JSON - even errors.
So before settling on an API, find out what your prospective APIs provide and what format you prefer to use.
3. Authentication mechanism
Which authentication mechanism is required (basic auth, API key, OAuth 2.0.)?
Using API keys is a way to authenticate an application accessing the API, without referencing an actual user. The application adds the key to each API request, and the API can use the key to identify the application and authorise the request. A benefit of API keys is that they are relatively easy to use, while a drawback is that since the key only identifies the application and not the user of the application, it often proves difficult to keep the key a secret.
HTTP Basic Auth is a simple method that creates a username and password style authentication for HTTP requests, and has similar benefits and security drawbacks to using an API key.
OAuth (Open Authorization) is an open standard access delegation framework for token-based authorization on the internet. It enables an end user's account information to be used by third-party services, without exposing the user's account credentials to the third party. It acts as an intermediary on behalf of the end user, providing the third-party service with an access token that authorises specific account information to be shared. Unlike granting access with other authorization mechanisms, the OAuth authorization is considerably faster – the user just needs to click on a button confirming access grant. However, while OAuth is good for authorization, it is considered to be not quite secure for authentication.
Developers should take these different authentication methods and their benefits and potential drawbacks into account when choosing an API.
4. API Limits
This was one of the main reasons I had to switch APIs midway. I realised much later on that the API I had chosen only allowed for a very limited amount of requests per endpoint. This was too restrictive for what I wanted to implement.
Many public APIs employ a request threshold per API Key. These thresholds are in place to prevent abuse and in some cases, motivate a user to upgrade their account. Trying to manage your request rate so as not to exceed the limits can greatly complicate your work as a developer.
Is this overhead worth it to you? Are there competing APIs that offer higher limits or none at all?
5. Technical Support and Community
When faced with challenges when using an API, you will likely need someone to answer your questions. Whether it’s regarding API limits, broken requests, timeouts and everything in between, there are things that only the API provider can help you with. Does the provider have support forums? Is the community helpful and active? What is the provider’s reputation for answering support questions in a timely and relevant manner?
Bonus: Reputation
Doing some research on the Internet can help you avoid surprises and find out about potential drawbacks before it's too late.
Can you find any other resources on the internet aside from the service provider’s page?
Does user's feedback on the service tend to be negative or positive?
Is the API used by well-known companies?
Depending on the scope of integration and the services it provides, picking an API can be a major commitment. This article feeds off the challenges I faced when using my first API, but is by no means an exhaustive list.
Do your research and consider the opportunity cost of using the best available public API vs building and maintaining your own backend.
In the API we trust.
Top comments (0)