api-contract-check

---
name: api-contract-check
description: Validate API contracts (RAML/JSON Schema/OpenAPI) against their implementations. Use when checking for API drift, reviewing schema changes, or verifying contract consistency.
---

# 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

For RAML definitions, verify:
- Base URI and resource paths match actual deployment
- Request/response types reference correct schemas
- Media types are correct (`application/vnd.{context}.command.{name}+json`)

### Step 4: Cross-Context Contract Verification

When context A consumes events from context B:

1. Read B's event schema from `{b}-domain/{b}-domain-event/src/main/resources/json/schema/`
2. Read A's event handler that processes B's events
3. Verify A correctly handles all required fields from B's schema
4. Flag any fields A ignores that might be important
5. Check version alignment — A's dependency version of B's event artifact

### Step 5: Generate Report

```
## API Contract Report: [service-name]

### Commands
| Command | Schema | Handler | Status |
|---------|--------|---------|--------|
| {context}.command.{name} | ✅ defined | ✅ implemented | OK |
| {context}.command.{name} | ✅ defined | ❌ missing field X | DRIFT |

### Queries
| Query | Schema | Handler | Status |
|-------|--------|---------|--------|
...

### Domain Events
| Event | Schema | Producer | Status |
|-------|--------|----------|--------|
...

### Cross-Context Contracts
| Consumer | Event | Producer Version | Consumer Version | Status |
|----------|-------|-----------------|-----------------|--------|
...

### Issues Found
- [severity] [description] — suggested fix
```

## Common Content-Type Patterns

CP uses custom media types for command routing:

```
application/vnd.{context}.command.{action-name}+json
application/vnd.{context}.query.{query-name}+json
```

Examples:
```
application/vnd.hearing.command.schedule-hearing+json
application/vnd.usersgroups.command.set-user-details+json
application/vnd.listing.query.get-court-schedule+json
```

The framework routes commands/queries to the correct handler based on the `Content-Type` header. Mismatched content types will cause silent routing failures.

## Use Alongside `cpp-apitests`

When extending tests in `cpp-apitests`, the response assertions in a `*IT.java` are contract checks in disguise. Before adding or changing an assertion:

1. Locate the producing service's contract (RAML for legacy contexts, OpenAPI for Modern by Default services)
2. Confirm the asserted field, type, enum value, and required/optional status match the contract
3. If the test diverges from the contract, the test — not the contract — is wrong; fix the test or open a contract-change ADR

For authoring guidance in `cpp-apitests`, see `cpp-test-authoring`.

More agent context in hmcts/claude

15 other files this repository gives its agents.