At this point you should have a well-defined API business strategy and documentation. This includes defining who your main API stakeholders are going to be, and deciding how the API will be consumed. By this point you should have answers to the following questions:
- What value is the API providing? Is it a means to distribute data or does it offer specific functionality that can be used to build apps?
- Who will consume the API? Are consumers interacting with your API to get access to data or are they consuming it on behalf of other users?
- How many consumers will the API have? Is it a private API consumed internally or is it going to be available to potentially millions of consumers?
Answering these questions will help you cut corners during the implementation process. Let’s start with understanding what you are trying to enable with your API so that you can define which methods and protocols you’re going to use.
Methods and Protocols
The best way to define methods and endpoints for your API is to follow the functionality you’d like to provide and choose the most appropriate standards and protocols. Identify what type of data manipulation your main API consumers usually have available.
If your main consumers are mobile apps, consider offering endpoints that ask for and respond with as little information as possible. This is to prevent large bandwidth consumption and speed up operations that involve calls to your API. If, by contrast, you’re offering an API that will mostly be consumed by the financial market, carefully study what frameworks they’re using and how they communicate with external APIs.
Whatever you do, we recommend not to follow the very latest trends presented as “the future.” Trends can and will change many times before they stabilize and become widely adopted, and your API will have to keep up with this market fluctuation. Determine what 80% of your target audience is using and offer that.
One of the most important aspects of API Management is defining and automating the process of controlling who can access your API and what measures are in place to enable access limitation, if needed.
Most API Management platforms provide some sort of access control features, including API call limit rating and consumer differentiation with the help of different paid plans. The very first access control feature to look for is how your API will authenticate and authorize consumers.
There are several options depending on what kind of consumers you’ll have and what kind of usage will occur:
- API keys: The simplest way to control access to your API. Usually you’ll have to issue one API key for each consumer and identification will be provided through an HTTPheader on each and every call.
- OAuth 2: Perhaps the most popular authorization standard used by Web APIs. OAuth 2 lets you combine token-based authentication with fine-grained access control based on user scopes. This is the best solution whenever API consumers are making calls on behalf of other users.
- Origin IP address: This can be combined with other access control methods or used on its own. Using it alone is done in cases where you’re providing an API to a very limited audience. To achieve better results, you should also add origin information to your logs and usage analytics.
Whatever access control strategy you choose, always remember that it must accommodate your API’s most popular use cases. As an example, it doesn’t make sense to use a simple API key based authentication if your main API usage is through a mobile app. In this case it would make sense to use OAuth and let the mobile app act on behalf of its users.
One way to proactively understand if your API is performing according to the documentation you provide and following your quality-of-service is to run periodic tests against individual endpoints. With monitoring in place, if any of the tests fail, you can hopefully fix the error before your consumers experience problems. These types of tests can be performed on your API:
- Performance-oriented: These are tests that make individual calls to each and every method your API provides. If a response takes longer than a specified time limit, it means that there’s a problem on that specific endpoint.
- Functional testing: This type of testing works by making singular calls to each API method to thoroughly test every API function, using different kinds of payloads, or even sending data that will produce errors. Responses are then compared to the expected behavior to locate errors.
- Use case testing: This is a more sophisticated type of test and can be achieved by combining calls to different endpoints into a single test. Each test should expect a specific response and execution time limit.
There are several tools that can help you run API tests periodically in an automated fashion. POSTMAN, for example, is a Chrome app that lets you run all the tests mentioned above. If you’re looking for something more SaaSy you can try Runscope, a service that periodically runs tests and reports on their results. Other helpful API monitoring solutions include APImetrics and API Science.
Even if everything is working as expected, sometimes you’ll need to introduce changes to your API. When this happens, consider the impact on your consumers and internal systems by:
- Informing consumers about changes: Establish a clear communication channel between you and developers using your API to inform them of changes in a transparent fashion.
- Keeping compatibility with previous versions: Ensure that any introduced change doesn’t break what was already working. Remember that your API consumers may not be able to update their systems immediately.
- Minimizing downtime: Don’t bring systems to a halt — even momentarily. Your build and deployment processes should guarantee that API changes won’t affect API calls and functionalities. API downtime might create downtime or loss of quality on the consumer side, so keep it to an absolute minimum.
Downtime can be minimized by following a Continuous Integration approach and testing your code thoroughly before deploying. Making sure that there are no breaking changes can be achieved by following a sound API versioning strategy. If you offer and maintain different versions of your API, consumers won’t feel the changes on the version they’re using. A helpful solution that bridges the gap between API doc changes and the consumer is the API Changelog, a tool that automatically discovers changes to your API documentation and informs subscribers.