Lesson 23 / 25
API Governance, Catalogues and AsyncAPI
Scale API practices across teams with style guides, catalogues and event descriptions.
By Rahul Agarwal · 15 years in web development
Many APIs, one experience
As organisations grow to dozens or hundreds of APIs, governance keeps them coherent without slowing teams down. Ingredients: an API style guide (naming, pagination, errors, versioning, security) expressed as lint rules; reusable components shared across APIs (error schemas, pagination envelopes, common parameters), published as a versioned library referenced with $ref; an API catalogue or developer portal (Backstage, SwaggerHub, Redocly, API gateway portals) listing every API with its owner, lifecycle stage, documentation and SDKs; design reviews for public or cross-team APIs; and lifecycle policies for deprecation and sunset. Event-driven interfaces need the same care: AsyncAPI describes channels, messages and their schemas for Kafka, RabbitMQ, MQTT and WebSockets, with similar tooling for docs, code generation and linting. Governance works best as a paved road: templates and automated checks that make the right thing easy, rather than manual approval gates.
Sharing components across APIs
A central, versioned library of common definitions referenced by each API.
# common/v1/components.yaml (published, versioned)
components:
schemas:
Problem: { $ref: './schemas/problem.yaml' }
Money:
type: object
required: [amount, currency]
properties:
amount: { type: string, pattern: '^\d+\.\d{2}$' }
currency: { type: string, pattern: '^[A-Z]{3}$', examples: [INR] }
parameters:
Limit: { $ref: './parameters/limit.yaml' }
Cursor: { $ref: './parameters/cursor.yaml' }
# orders-api/openapi.yaml
components:
schemas:
Order:
type: object
properties:
total: { $ref: 'https://specs.example.com/common/v1/components.yaml#/components/schemas/Money' }
responses:
ValidationProblem:
description: Invalid request
content:
application/problem+json:
schema: { $ref: 'https://specs.example.com/common/v1/components.yaml#/components/schemas/Problem' }Building codes for a city
A city does not inspect every brick, but it publishes building codes, offers standard designs and checks key points automatically. API governance works the same way: shared rules and components, with automation doing most of the checking.
Quick check: Which specification describes event-driven, message-based APIs in the way OpenAPI describes HTTP APIs?
- GraphQL SDL
- AsyncAPI
- WSDL
- JSON:API
Answer
AsyncAPI — AsyncAPI describes channels and messages for brokers and other asynchronous protocols.