api-contract-check

API Contract Check

Validates that API definitions (RAML, JSON Schema, OpenAPI) match their implementations across CP services.

When to Use

• User asks to "check API contracts", "validate schemas", "find API drift"
• User has changed a RAML/schema file and wants to verify consistency
• User wants to understand the API surface of a context service
• Before integrating with another context service's API

Process

Step 1: Identify API Definitions

Legacy Context Services (RAML + JSON Schema)

API definitions live in predictable locations:

{name}-command/{name}-command-api/src/raml/
    json/                           # Request payloads
    json/schema/                    # JSON Schema definitions
    {context}.command.{action}.raml # RAML endpoint definitions

{name}-query/{name}-query-api/src/raml/
    json/                           # Response payloads
    json/schema/                    # JSON Schema definitions
    {context}.query.{action}.raml   # RAML endpoint definitions

Modern by Default Services (OpenAPI/Swagger)

API definitions are generated from annotations:

• @Operation, @ApiResponse on controller methods
• springdoc-openapi auto-generates /v3/api-docs
• Check src/main/resources/application.yaml for springdoc config

Step 2: Cross-Reference with Implementations

For each API definition found:

1. Command APIs — verify the command handler processes all fields defined in the schema
2. Query APIs — verify the query handler returns all fields defined in the response schema
3. Event schemas — verify domain events contain all fields defined in the event schema
4. Inter-service contracts — verify consuming services use the same schema version as the producing service

Step 3: Check Schema Consistency

For JSON Schemas, verify:

• $ref references resolve to existing schema files
• Required fields are enforced in handler code
• Enum values match actual usage in code
• Date/time formats follow ISO 8601