Skip to content

API Contracts

API contracts are the machine-readable agreements between services. As a solution architect, you author and maintain these contracts. Developers implement against them.

OpenAPI Specs (REST APIs)

Every microservice has an OpenAPI 3.x specification in architecture/specs/.

File Location

architecture/specs/
  svc-check-in.yaml
  svc-scheduling-orchestrator.yaml
  svc-guest-profiles.yaml
  svc-reservations.yaml
  ... (23 total)

What a Spec Includes

Each spec defines:

  • Endpoints — every REST endpoint with method, path, parameters, and request/response schemas
  • Schemas — data models with field types, descriptions, nullable annotations, and enums
  • Security — authentication requirements per endpoint
  • Server URLs — where the service listens
  • Contact metadata — owning team and support channels

Editing a Spec

When your solution design requires API changes:

  1. Open the spec in architecture/specs/{svc-name}.yaml
  2. Make the changes (add endpoints, modify schemas, add fields)
  3. Verify backward compatibility (see below)
  4. Commit and push — CI regenerates Swagger UI, microservice pages, and sequence diagrams

Backward Compatibility Rules

Safe changes (backward compatible):

  • Adding a new endpoint
  • Adding a new optional field to a response schema
  • Adding a new optional query parameter
  • Adding a new enum value

Breaking changes (require migration plan):

  • Adding a new required field to a request schema — existing callers will fail
  • Removing a field from a response schema — existing consumers may break
  • Renaming an endpoint path — existing callers will get 404
  • Changing a field's type — existing parsers may fail
  • Removing an enum value — existing callers using that value will get validation errors

When a breaking change is unavoidable, the solution design must include:

  1. A migration plan (how to move consumers from old to new)
  2. A deprecation timeline (how long the old contract is supported)
  3. An ADR documenting the decision and trade-offs

Schema Completeness Checklist

When reviewing or writing schemas:

  • Every field has a type
  • Every field has a description
  • Nullable fields have nullable: true with documented null semantics
  • Enum values match known domain values (e.g., adventure categories)
  • info.version reflects the latest change
  • Required vs. optional is explicit for every field

Swagger UI

Every spec gets an interactive Swagger UI page at /services/api/{svc-name}.html. These are auto-generated by portal/scripts/generate-swagger-pages.py — do not edit them.

AsyncAPI Specs (Events)

Domain events use AsyncAPI specifications in architecture/events/.

File Location

architecture/events/
  svc-check-in.events.yaml
  svc-reservations.events.yaml
  svc-scheduling-orchestrator.events.yaml
  ... (8 total)

What an Event Spec Includes

Each spec defines:

  • Channels — Kafka topics
  • Messages — event payload schemas
  • Producers — which service publishes
  • Consumers — which services subscribe (documented in architecture/metadata/events.yaml)

Adding a New Event

  1. Add the event to the producer's AsyncAPI spec in architecture/events/{svc-name}.events.yaml
  2. Add the event to architecture/metadata/events.yaml (producer, consumers, topic)
  3. Regenerate: bash portal/scripts/generate-all.sh

Event Schema Design Rules

  • Events are immutable facts — they describe something that happened, not a command
  • Use past tense for event names: CheckInCompleted, ReservationConfirmed, WaiverExpired
  • Include a correlation ID for tracing across services
  • Include a timestamp for event ordering
  • All fields should have types and descriptions
  • New fields must be optional (additive-only evolution — see ADR examples)

Contract Testing

API contracts are verified through Spring Cloud Contract testing (ADR-013).

How It Works

  1. Architect writes the OpenAPI spec — this is the contract
  2. Producer service generates contract tests from the spec — these verify the service implements the contract correctly
  3. Consumer services generate stubs from the spec — these verify the consumer code correctly calls the API
  4. CI runs both on every PR, catching contract drift before it reaches production

What This Means for Architects

  • Every spec change you make triggers contract test re-generation
  • If your spec change breaks a consumer's contract test, that consumer team needs to update their code
  • This creates a built-in feedback loop: you cannot silently break API contracts

See ADR-013 for the full decision rationale.

Viewing Specs in the Portal

Microservice Deep-Dive Pages

Every service has an auto-generated page at /microservices/{svc-name}/ that includes:

  • All endpoints with sequence diagrams (139 total across all services)
  • Data store documentation with ERD diagrams
  • Cross-service integration flows
  • Direct links to Swagger UI

API Explorer

The API Explorer at /api-explorer.html provides a unified search across all 23 service specs.

Spec Analysis Checklist

When analyzing existing specs or reviewing proposed changes:

  1. Schema completeness — all fields have types, descriptions, and nullable annotations
  2. Version consistency — info.version matches the service's last documented change
  3. Missing fields — look for fields the business domain requires but the spec omits
  4. Enum validation — values match known domain values
  5. Backward compatibility — new required fields break existing consumers
  6. Cross-reference with source — verify that source code behavior matches the published spec

Reference