API Lifecycle Development Stage: Deploying Your API

The API Lifecycle is an agile process for managing the life of an API. The common API Lifecycle is composed of four distinct phases: Analysis, Development, Operations, and Retirement.

During the course of this article, you’ll come to understand the actions to take as well as the most important challenges to address during an API’s Development phase. We’ll consider what implementation options are available and explore API Management and why it matters. We’ll define API Usability and why it’s important, and we’ll consider what immediate steps to take after your API is deployed.

The most important action in this API Lifecycle phase is actually implementing the API and bringing it to life. Read on to learn more about this process and to understand what factors contribute to choosing the best combination of standards and programming languages for your API.

Things to Consider During Implementation

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.

SDK Programming Languages

Choosing how you’ll offer access to your API is directly related to how your API will be consumed. Will it mainly be consumed by mobile app developers? Then offer ready-to-use mobile SDKs. Brainstorming your potential API use cases is the first step in choosing how your SDK will be packaged.

If you’re not 100% sure about how your API will be used you can always offer an SDK in several popular programming languages. Algolia, a search engine API, is following this approach by offering an easy way to use their service in languages such as Ruby, Python, Node, PHP or Objective-C. Be aware though that maintaining a large number of SDKs is not an easy task as your API evolves and methods change. APIMATIC and REST United are two services that offer automatic SDK generation. With these tools, whenever your API changes you can rerun the SDK generation to make fresh code versions available to your consumers.

API Management

After you implement your API endpoints and decide how consumers will interact with your API, you must consider ongoing operations. The most important factors are controlling your API access conditions and determining how to behave in usage peaks. You can follow a DIY approach or use an API management service such as 3scale or Apigee.

Whatever solution you choose, remember that you’ll become tied to the way it works. Carefully define long term objectives as well as common scenarios you want to address. If you choose a solution that doesn’t offer what most of your API consumers use, then you’ll likely be forced to pivot in the long term.

Access Control

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 most simple 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 HTTP header 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.

More on API Access Control: Deep Dive into OAuth and OpenID Connect

Maintenance

While launching your API can be an exciting challenge, keeping it up and running is often seen as something boring. API maintenance is often delegated to a second plan and only considered after things start to go wrong. Don’t follow this path; implement a good maintenance plan from the start.

The usual activities around maintaining your API are related to documentation, communication with consumers and proactively understanding if something is not working as expected. As such, a big part of maintenance is done by periodically testing your API to make sure that everything is working as documented.

Testing

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.

Managing Changes

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.

Next Steps:

As you now understand, developing an API is not limited to writing the code and making it available. Understanding your API use case plays a major role in building the foundation of your offering. Maintaining proper API health means never leaving it unattended — as you risk a decrease in consumer retention and a damage to your brand.

This stage of the API Lifecycle is so critical that numerous services have been launched and many startups created just to help companies deal with all that’s involved. These tools will help you understand what you have to do next. If you are motivated to introduce major changes to your API we recommend you visit the Analysis Stage to treat those iterations as a brand new API launch or version. Otherwise, jump into the Operations Stage and run your API like a product, fostering its user base.