API Contract Design

API Contract Design

When to activate

During architecture design phase when defining service boundaries and integration points. Triggered by: component breakdown complete, external integrations identified, or third-party API consumption planned. Should be done before any implementation starts (API-first design).

When NOT to use

Not for implementing APIs (this is contract design, not coding). Not for existing APIs that are already in production (use versioning-strategy instead). Not for internal-only communication (use message queues or direct calls). Not without clear understanding of consumers and use cases.

Design Checklist

1. API Scope

   • Who consumes this API? (internal services, external partners, public)
   • What business operations does it enable?
   • What data moves through it? (sensitivity, compliance requirements)
   • Latency requirements? (real-time, near-real-time, batch)
   • Throughput expectations? (req/sec, concurrent users)

2. Resource Design

   • REST resources identified (nouns, not verbs)
   • CRUD operations clear for each resource
   • Hierarchies defined (parent/child resources)
   • Filtering/sorting/pagination strategy
   • Relationships between resources documented

3. Error Handling

   • HTTP status codes mapped to scenarios
   • Error response format consistent
   • Error codes documented (for client handling)
   • Retry strategy (when safe to retry)
   • Detailed error messages for debugging

4. Security & Auth

   • Authentication strategy (API key, OAuth2, mTLS)
   • Authorization (scopes, roles, resource-level)
   • Rate limiting strategy (calls/sec per client)
   • Request signing or encryption needed?
   • Audit logging for sensitive operations

5. Versioning & Compatibility

   • Versioning strategy (URL path, header, query param)
   • Deprecation timeline (when old versions sunset)
   • Migration guide for clients
   • Backward compatibility rules (what can change)

6. Documentation & Testing

   • API spec complete (OpenAPI, GraphQL SDL)
   • Examples for every endpoint
   • Integration tests for key workflows
   • Mock server for early client development
   • API changelog maintained

Output Format

API Specification

Overview

Title: [API name]
Version: [version]
Base URL: https://api.company.com/v1
Contact: [name, email]
License: [MIT, etc.]

Authentication

Type: OAuth2 / API Key / mTLS
Scheme: Bearer [token]
or
Header: Authorization: Bearer {access_token}
Scopes: [read:orders, write:orders, read:customers, etc.]

Endpoints (organized by resource)

GET /resource/{id}

Description: Fetch a single [resource]

Parameters:
  id (path, required): Resource ID

Response (200 OK):
{
  "id": "123",
  "name": "Example",
  "created_at": "2026-06-13T10:30:00Z",
  "status": "active"
}

Errors:
  401: Not authenticated
  403: Forbidden (insufficient scope)
  404: Resource not found
  429: Rate limited (too many requests)

POST /resource

Description: Create a new [resource]

Request Body:
{
  "name": "New Item",
  "type": "premium"
}

Response (201 Created):
{
  "id": "124",
  "name": "New Item",
  "type": "premium",
  "created_at": "2026-06-13T10:31:00Z",
  "status": "pending"
}

Errors:
  400: Validation failed (see body for details)
  401: Not authenticated
  422: Unprocessable entity (data conflict)

PUT /resource/{id}

Description: Update a [resource] (full replacement)

Parameters:
  id (path, required): Resource ID

Request Body:
{
  "name": "Updated Item",
  "type": "premium",
  "status": "active"
}

Response (200 OK):
{
  "id": "123",
  ...
}

Errors:
  400: Validation failed
  404: Not found
  409: Conflict (version mismatch or concurrent update)

PATCH /resource/{id}

Description: Partial update [resource]

Request Body (only fields to update):
{
  "status": "inactive"
}

Response (200 OK): [Updated resource]

Errors: [same as PUT]

DELETE /resource/{id}

Description: Delete a [resource]

Response (204 No Content): [empty]

Errors:
  404: Not found
  409: Cannot delete (foreign key constraint, etc.)

GET /resource?filter=value&sort=name&page=1&per_page=20

Description: List [resources] with filtering and pagination

Query Parameters:
  filter (optional): Filter by [criteria]
  sort (optional): Sort by [field]. Prefix with - for DESC
  page (optional, default: 1): Page number
  per_page (optional, default: 20): Results per page

Response (200 OK):
{
  "data": [
    { ... },
    { ... }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 156,
    "pages": 8
  }
}

Error Response Format (consistent across all endpoints)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields are invalid",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      }
    ]
  }
}

Status Codes

Versioning Strategy

Approach: URL path versioning (/v1/, /v2/)

Compatibility Rules:

• Can add optional fields to request/response (old clients ignore them)
• Cannot remove required fields
• Cannot change field data type
• Can add new endpoints
• Can deprecate old endpoints (with warning)

Deprecation Timeline:

• Current: v1 fully supported
• Supported: v1 (6 months remaining)
• Deprecated: v1 (supported for 6 months, then sunset)

Migration Guide:

# Migrating from /v1/ to /v2/

Changes:
- `created_at` is now ISO 8601 format (was Unix timestamp)
- `status` field moved inside `metadata` object
- New required field: `account_id`

Before:
GET /v1/orders/123
{
  "id": "123",
  "created_at": 1623600600,
  "status": "shipped"
}

After:
GET /v2/orders/123
{
  "id": "123",
  "created_at": "2026-06-13T10:30:00Z",
  "metadata": {
    "status": "shipped"
  },
  "account_id": "acme"
}

Rate Limiting

- Authenticated: 1000 req/min per client
- Unauthenticated: 100 req/min per IP
- Spike allowance: 2x limit for 10 seconds

Headers returned:
RateLimit-Limit: 1000
RateLimit-Remaining: 956
RateLimit-Reset: 1623600660

Webhooks (if applicable)

POST https://customer.example.com/webhooks/orders

Event: order.created

Payload:
{
  "event_id": "evt_123456",
  "event_type": "order.created",
  "timestamp": "2026-06-13T10:30:00Z",
  "data": {
    "id": "ord_789",
    "customer_id": "cust_456",
    "amount": 129.99
  }
}

Signature (HMAC-SHA256):
X-Signature: sha256=abc123def456...