Fotolia
5 stages of an API lifecycle explained
APIs are not just a component you can set and forget. Developers need to plan, create, deploy and monitor APIs to keep them aligned with business needs, as well as know when it's time to retire them.
APIs help diverse software products interoperate and work together. But APIs are software too, and each one has a lifecycle that takes it from cradle to grave.
An API is software that provides a means of communication or interaction between other software components or systems. For example, when a business schedules a customer for an appointment, the scheduling application might use a Google API to send an appointment reminder to the customer's Google Calendar.
APIs often play a role in iterative software development processes, which move at a rapid pace. However, developers must maintain API stability while the associated applications undergo frequent updates and changes. Continuously releasing new versions of an API can be troublesome for the software and services that depend on it.
Let's take a closer look at APIs and consider the basic stages of an API lifecycle.
An API lifecycle
Although opinions differ about the actual parts of an API lifecycle, this discussion uses five classic phases: planning, development, testing, deployment and retirement.
1. Planning phase
Any API development project must begin with planning and design. Have business team members identify which services and capabilities an API should expose. Document specific business needs and refine the initial API goals into a comprehensive set of functional and nonfunctional requirements.
Here is an example of requirements for an API: A mapping service needs to center the map on a user's location. Similarly, a user should be able to select a destination location by inputting a physical address or other data. This means the application must be able to examine location data and connect with a mobile device's GPS system.
Once API requirements are established, development teams can make informed design decisions on naming conventions, architectural styles and the specific protocols to use. Planning and design should result in an API specification that describes the methods and operations supported by the interface, as well as any technical constraints.
2. Development phase
APIs can be written in many programming languages, including PHP, Python, Ruby, .NET, C#, Java and Perl. Coding and testing might take numerous iterations, but development teams should not release an API into production before it is stable. Ultimately, API development needs excellent planning, coding, and testing skills, along with the discipline needed to minimize customer-facing API changes.
API development can be accomplished by a single developer, but is more frequently handled by a separate, dedicated API development team. A team approach allows multiple developers to access, build, and maintain the organization's API portfolio in a carefully controlled manner. In addition, multiple developers make it easier to create the documentation, test cases and even some of the marketing materials that would be required to make public APIs successful for the business.
Since it is a team effort, multiple developers will need to cooperatively access and maintain their APIs. The entire API team should be able to see and interact with API code, documentation and test files. This also makes it important to implement comprehensive search and versioning controls, which helps authorized developers locate APIs by criteria, such as project and version.
API development planning should always circle around these three considerations:
- How you will track the API's use, performance, errors and other important metrics.
- Security components, notably OAuth 2.0 authorization and API-key validation.
- Performance and accessibility issues, such as throttling and rate limiting, to ensure adequate API access.
3. Testing phase
Developers must thoroughly test each iteration of the API for functionality, performance and user acceptance. Testers can loop unsatisfactory results back to developers to further build and refine the API code.
Functional testing validates that every feature or function operates as intended. Use mockups and test versions to evaluate the API's functionality against its specification. Functional testing also emphasizes focus on the security and error handling capabilities that ensure the API is protected from crashes or attacks.
Performance testing evaluates how the API performs under load. Many APIs are subject to erratic traffic and unpredictable load conditions. Performance testing metrics measure how well the API performs under heavy loads, such as the time it takes to respond to a certain application request.
Acceptance testing tracks the API's use and gauges whether it achieves its intended business purpose. Acceptance testing can reveal any new requirements that may arise from a change in the business process or the API itself. It can help identify possible changes to existing functions that could make the API more useful. For example, in cases where data might be passed to or from the API, acceptance testing can reveal the need to pass more or different data as a parameter argument.
The restaurant paradigm
One of the easiest ways to understand what an API is and how it works is to think about it as a menu at a restaurant. A menu shows food, drink and other options for ordering, and is the primary means for a diner to interface with what the restaurant offers. When diners order from a menu, they don't need to know anything about the kitchen gear, staff or how the restaurant works. Just like the customers, the software can "order" what it needs by looking at the API without needing to understand the application it calls.
A restaurant will also update menus periodically to add new offerings or remove unpopular ones. If the content or format of a menu changes too frequently, diners might get confused and frustrated that they can't find what they want. But as long as a menu is reasonably stable, it doesn't necessarily matter to the customer if the kitchen, staff or other restaurant operations change behind the scenes. Again, just like a customer at a restaurant, a piece of requesting software may experience failures if it cannot easily find the resources it needs through the API it depends on.
4. Deployment phase
Once an API is stable and secure, it is ready for production. However, as with many software products, an API's initial release may act as a second stage of performance testing and validation.
For example, developers may release a new API into a blue/green deployment environment, where developers try the newest API version with the software without impacting the live version. Ideally, by the time developers have readied their newest release, the API is ready for the full production environment. A key part of this process is gathering metrics that track the API's performance, such as the number of errors it experiences.
Developers must minimize the disruptions caused by a new API version. A well-written API should include a version call function that can retrieve a known-good version to put into production in case the new one proves unsuitable.
API changes that fix bugs or enhance performance won't typically affect API calls and responses. However, new parameters and arguments for authentication, or other fundamental design changes, can force users to perform software updates before they can access the new API version.
5. Retirement phase
Developers can expand and update APIs over time to enhance business value, but every API accrues infrastructure and support costs as time goes on. Eventually, software teams retire old APIs and old versions of APIs so they don't waste resources supporting them.
As such, a business needs to diligently plan the migration path from one API version to another and learn to maintain multiple API versions at a time while refining new releases. Software teams need an end-of-life plan in place in order to discontinue APIs without drastically affecting day-to-day operations.
Monitoring is a huge part of this retirement process, especially when it comes to tracing the age and history of an API. For example, a business might discover that some APIs have gone virtually unused in 90 to 120 days. Yet, they are still hosted in the infrastructure, consuming resources and creating costs. That's why tracking these APIs is such an essential part of an effective, balanced API retirement plan.
