Requirements - Solution Design & Methods - SD10 - API Lifecycle

The API follows the lifecycle policy best practice as set out within Sunsetting (deprecation and retirement) policy. This should include any enforcement arrangements.

Requirement description

This requirement is concerned with the management of APIs throughout their lifecycle, particularly when APIs are changed, deprecated or retired.

Consumers should receive appropriate notice of changes, lifecycle states should be clearly managed, and there should be defined enforcement arrangements to ensure consumers migrate away from deprecated APIs before retirement.

The objective is to minimise disruption, reduce technical debt and ensure that API consumers can plan and manage change effectively.

In simple terms:
APIs should have a managed lifecycle with clear deprecation and retirement processes that are communicated, governed and enforced.

Scoring rubric table – API Lifecycle Management

Score What it looks like Typical evidence Key gaps / risks
0 No evidence that API lifecycle management exists. APIs can be changed, deprecated or retired without any documented process. No lifecycle policy, no versioning strategy, no retirement approach, no consumer communications. Significant service risk. API changes may cause unexpected consumer disruption, service failures and unmanaged technical debt.
1 Limited awareness of lifecycle management. Changes are handled informally and are largely dependent on individual teams. Ad-hoc communications, informal retirement discussions, undocumented versioning approaches. High-risk gaps. Consumers may receive insufficient notice and there is little evidence that deprecation is actively managed.
2 Some lifecycle processes exist. Deprecation and retirement activities occur but are inconsistent across APIs. Partial lifecycle guidance, some retirement plans, evidence of consumer notifications for selected APIs. Significant notable gaps. Lifecycle activities may not be consistently applied, governed or monitored.
3 Much of the lifecycle process is defined and followed. Deprecation and retirement activities are documented and communicated for most APIs. API lifecycle documentation, versioning standards, retirement plans, consumer communications, change records. Notable gaps remain. Some APIs lack consistent lifecycle management, monitoring, consumer engagement or enforcement arrangements.
4 Most APIs follow a defined lifecycle approach. Deprecation, retirement and enforcement arrangements are documented, governed and consistently applied. Approved lifecycle policy, maintained API catalogue, migration plans, retirement schedules, consumer impact assessments, governance review records. Minor gaps only. Remaining exceptions are understood, documented and subject to agreed remediation.
5 Comprehensive and exemplar lifecycle management. Lifecycle processes are actively monitored, governed and continuously improved. Consumer migration is effectively managed and supported. Lifecycle metrics, regular governance reviews, documented enforcement mechanisms, migration tracking, consumer engagement plans, lessons learned, continuous improvement activities. Minimal or no significant gaps identified.

What assessors should look for

  1. Defined lifecycle process – Evidence that API lifecycle states such as active, deprecated and retired are formally managed.
  2. Deprecation management – Evidence that API consumers receive appropriate notification, guidance and migration support.
  3. Retirement planning – Evidence that API retirement activities are planned, documented and communicated.
  4. Version management – Evidence that API versioning aligns with lifecycle objectives and supports consumer transition.
  5. Enforcement arrangements – Evidence that retirement and migration activities can be enforced where required and are not purely advisory.
  6. Governance and oversight – Evidence that lifecycle activities are reviewed, owned and maintained over time.

What separates a 3 from a 4 or 5

A score of 3 generally indicates that lifecycle management exists and is being followed for most APIs, with acceptable evidence of communications and retirement planning. However, notable gaps remain in consistency, governance, monitoring or enforcement.

A score of 4 requires clear evidence that lifecycle activities are governed, consistently applied across APIs, and supported by documented enforcement and migration arrangements.

A score of 5 requires a mature and demonstrably effective lifecycle management capability. API deprecation and retirement are actively managed using metrics, governance reviews, consumer engagement and continuous improvement processes.

Suggested evidence examples (not SAF-mandated artefacts)

  • API lifecycle policy and standards
  • API catalogue showing lifecycle status
  • Versioning strategy documentation
  • Deprecation notices issued to consumers
  • Migration plans and transition guidance
  • Retirement schedules and implementation records
  • Consumer communications and engagement records
  • Governance approvals and review outputs
  • Metrics showing migration progress and consumer adoption

Updated: 04 September 2026 (SAF Version 1.1)