16 REST API design best practices and guidelines 5 major reasons to adopt an API management platform

API lifecycle management

API lifecycle management is a part of API management that supports the design, development and maintenance of APIs, including their transitioning from design and testing to a production environment.

APIs are increasingly recognized as being almost a component of an application or service. This means that like any other program element, they have a lifecycle from planning through retirement, and lifecycle management to assure they progress through their stages in an orderly way. Because APIs link components -- and at the same time are essentially components -- of software, loss of control of APIs would create a far-reaching and critical risk for any business dependent on them.

API management is generally recognized as requiring three things:

API design requires a developer portal to expose the APIs and support their use in application development. An API gateway provides API security, thereby securing the underlying components used to fulfill the functional promise of each API.

While API lifecycle management is a separate capability on this list, it has to be exercised in synchrony with the other two capabilities, and also supported by additional tools for gathering API usage and status information. The need to support all these capabilities has encouraged many users to look for full-scope API solutions, but some will still do their own selection and integration of tools and capabilities, picking products and practices for each of the three areas.

Stages of API lifecycle management

It's generally agreed that APIs undergo five phases, and that API design must consider them all. These phases are:

  • planning and design
  • development
  • testing
  • deployment and use
  • retirement

Various vendors and experts will use different names for (and offer different numbers of) these stages of the lifecycle, but the general process is very consistent. It's tempting to look for the approach with the largest number of stages to ensure everything is covered, but the additional refinement tends to impose a specific structure on the process, which then limits tool selection.

Five stages of API lifecycle

API lifecycle management challenges

The number one challenge for API lifecycle management is the efficient operation of dependent applications. APIs are a means to an end and not the end itself, and that is easily lost when too much focus on lifecycle processes for APIs causes a loss of focus on their impact. It's important to integrate API lifecycle management with the supported application's lifecycle management, and with the development portal used to create both the APIs and their applications.

One broad challenge for API management are API endpoints. APIs are parts in a multi-component workflow. As such, they represent relationships as well as services in the traditional service/microservice sense. That means there is nothing "independent" about an API, and considering it in the context of the service it represents can lead to major errors. It's important to consider all APIs in terms of the entire workflow they stitch together, and to be able to manage the lifecycle of all the workflow elements in harmony.

Best practices for API lifecycle management

The most important thing to remember in defining API lifecycle management practices is to focus first on how APIs are used and the issues that the use has exposed. The optimum practices for API lifecycle management in development should be identified before selecting tools. Otherwise, early tool consideration will shape best practices and limit options later.

For API management overall, users should consider a unified solution for the three capability areas defined above, unless they have a strong reason to look for specific solutions in each. API management tools are easily integrated with each other. In most cases, they adapt well to overall development tools and practices. Having developed a vision for API usage before looking at specific API management tools and techniques will help pick the right general solution and know when a general solution may not be the best option.

Most users who find that a general toolkit for API management doesn't work for them will be users who have evolved an API strategy based on per-project decisions, without central API control. If this is the case, it's still smart to explore the costs and benefits associated with a shift to an API management approach that's based on a unified API management platform.

API management tools
A list of components of API management tools.

Representative API lifecycle management tools

The following three broad approaches can be used to select API lifecycle management tools:

  • Use the API lifecycle management tools associated with the primary application development toolkit.
  • Select an overall API lifecycle management tool for all the API lifecycle stages.
  • Choose the best tool for each phase.

Integrating API management with general development is the theme of IBM's Cloud Pak, which are appmod solutions integrated with IBM's API Connect. Organizations committed to IBM's development tools would find this approach easy to adopt and completely integrated.

Red Hat's OpenShift platform includes development facilities, and its 3scale API management solution integrates will with it. Competitor VMware offers its Tanzu competitor to OpenShift, and supports the integration of the WSO2 API Manager, which is also available as an open source tool.

All three of these solutions are integrated with overall application development but can be adopted as an overall API lifecycle management tool independently. In that space, Apigee Edge is perhaps the best-known competitor, with other options including Mulesoft Anypoint, Axway, SwaggerHub and Kong. All these products work well as API managers, but Anypoint is generally seen as easier to integrate at a broader development level.

Anypoint is also likely to be easier to integrate with other API management capabilities for users who want to employ their own API gateways and follow a best-of-breed self-integrated approach to API management. Most such users will want to adopt one of the integrated solutions listed above, then customize it for their own use by replacing one or more of the three components (API design, API gateway and API lifecycle management).

Public cloud providers also offer API management tools, and these may be the best approach if the development target is public cloud computing or hybrid cloud applications where most API workflows are in the public cloud portion. Amazon's AWS API management tools make the point of saying that simple RESTful APIs may not require formal API management and support basic API gateway capabilities as well. Microsoft and Google both emphasize multi-cloud and hybrid cloud API management in their offerings.

This was last updated in April 2021

Continue Reading About API lifecycle management

Dig Deeper on API design and management

Software Quality
  • How to test a predictive model

    Strategies for testing predictive models and analytics emphasize data quality, real-time testing and code redundancy, as well as ...

  • The dos and don'ts of visual testing

    The visual aspect of an application is an important part of UX. Defects can potentially result in lost sales and damaged ...

  • 3 QA testing tools to consider

    QA testers need to be able to put applications and APIs through their paces. Here are some examples of tools that can help with ...

Cloud Computing