[ADP-42] API Lifecycle Management

Overview

API Lifecycle Management involves several stages:

1. Design: Define the purpose, functionality, and structure of the API.
2. Development: Implement the API's functionality.
3. Testing: Ensure the API works as expected and meets performance requirements.
4. Publication: Release the API and make it available for use.
5. Deprecation: Mark the API as deprecated and plan for its retirement.
6. Retirement: Completely remove the API.

Preview API

During the first three stages of an API's lifecycle, it is classified as an API preview.

API previews provide a valuable opportunity to collect feedback before the official release, enabling development teams to identify potential issues and make necessary adjustments.

• You MAY release API documentation that is in a preview state, provided it is properly flagged.
  • You SHOULD use x-api-state: preview or include a preview tag within your OpenAPI documentation to explicitly indicate the API's preview status.
• Clients MUST be aware that an API in preview may:
  • be incomplete
  • lack stability (in terms of backward compatibility)
  • not be ready for production use (even if it is featured on the production API documentation site)

Retire API

• If the API audience is greater than COMPANY_INTERNAL, you MUST inform clients when an API is being deprecated by using the following headers: Deprecation and Sunset.
  • You SHOULD use the Deprecation header to inform the API is in a deprecated state and set deprecated in the OpenAPI document. See HTTP Headers - Deprecation and OpenAPI Operation: Deprecation
  • You SHOULD use the Sunset header to indicate the date when the requested API will become unavailable. See Sunset

  INFO

  COMPANY_INTERNAL refers to APIs that are only used internally within the company and have not been made public to external customers. For more details, please refer to API Audience.

• An API being retired first enters the Deprecation state, then the Sunset state, before final retirement.
• It's possible and often recommended to use both headers simultaneously.

Versioning API

• MUST choose the strategy that best fits your API and user needs. Whichever method you choose, clearly explain your versioning strategy in the documentation. See API Versioning

Handling Dependent Clients

When deprecating an API:

1. Communicate early and often with API consumers.
2. Provide clear migration paths to newer versions or alternative APIs.
3. Offer support and documentation for transitioning.
4. Consider maintaining the old version for a reasonable period to allow clients to migrate.

Best Practices

• Design with the future in mind, allowing for extensibility.
• Use semantic versioning for clear communication of changes.
• Maintain comprehensive documentation throughout the API lifecycle.
• Regularly review and update APIs based on usage metrics and feedback.
• Automate as much of the lifecycle management as possible, including testing and deployment.
• Implement robust monitoring and logging to quickly identify and resolve issues.
• Provide sandbox environments for API consumers to safely test and integrate.
• Establish clear Service Level Agreements (SLAs) and ensure adherence.
• Regularly communicate with API consumers to gather feedback and understand their needs.
• Consider implementing an API management platform to streamline management across the entire lifecycle.

Related ADPs

• Sunset
• Deprecation

Reference

• Deprecation Header Draft
• RFC 8594 - The Sunset HTTP Header Field
• RESTful API Design Best Practices
• API Versioning Methods
• Evolving HTTP APIs
• API Lifecycle Management Video