API Governance, Catalogues and AsyncAPI

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.

त्वरित जाँच: Which specification describes event-driven, message-based APIs in the way OpenAPI describes HTTP APIs?

• GraphQL SDL
• AsyncAPI
• WSDL
• JSON:API