Skip to content

Latest commit

 

History

History
20 lines (14 loc) · 2.65 KB

change-management.md

File metadata and controls

20 lines (14 loc) · 2.65 KB

Change Management

The API landscape is always changing. When you are API-first, this is a good thing. You have control over the rate of change and can effectively communicate changes to your consumers. Being API-first allows you to leverage change to your advantage, iterating upon your APIs as needed, not just to keep up with the pace of change, but to move it forward yourself.

Elements

  • Lifecycle - Without having a clear definition of the API life cycle, and without being able to discuss it with your teams using a shared vocabulary, change will become exponentially more difficult for you.

  • Source of Truth - You must always have a designated source of truth where code and artifacts are stored, evolved, synced, and forked, and where they are used across teams and contributors. Everyone must be working for the same truth.

  • Contract-Driven - Open source specifications like OpenAPI, AsyncAPI, JSON Schema, GraphQL, Protocol Buffers, and WSDL are used to govern the production and consumption of APIs, ensuring there are machine- and human- readable contracts in place.

  • Versioning - You need to apply a semantic, date-based, or other versioning strategy to API contracts and artifacts, helping communicate change as APIs are being produced to keep consumers up to speed.

  • Source Control - Use existing source control to manage change across API operations, making sure artifacts are available to show you what change looks like. That will minimize breaking changes, while keeping API contracts in alignment with deployments.

  • Releases - Provide organized and communicated releases for APIs, pausing for a moment to identify, consider, and discuss changes. Provide a clear milestone that can be shared between producers and consumers of each API.

  • Provenance - Without a record of the past, it is very difficult to know where you are going. That makes architectural decision records, change logs, and other provenance solutions a critical part of optimizing API velocity.

  • Automation - Contracts, versioning, and API release should always be as automated as possible. Use existing source control and CI/CD, but also be sure to leverage monitors for scheduling and orchestrating the way change is managed across all APIs.

Change is inevitable. APIs allow you to standardize and communicate change as it happens, helping API producers and consumers stay in alignment. As a result, consumers are more likely to keep pace with each version of APIs they are using.

Without a well-defined API life cycle, machine-readable API contracts, and a repeatable and automatable release process, seeing and managing change will be much more difficult.