Designing API Contracts

Overview

Design RESTful API contracts that map user actions to endpoints with complete schema definitions and comprehensive error handling. Every user action becomes an endpoint; every endpoint has request/response schemas and error handling.

When to Use

• Designing new API endpoints for a feature

• Mapping user actions to HTTP methods and paths

• Creating OpenAPI specifications from requirements

• Defining request/response schemas for endpoints

• Documenting error responses for an API

• Integrating with existing API patterns (brownfield)

• Creating contracts/ directory artifacts

When NOT to Use

• GraphQL API design - Different paradigm, not RESTful

• WebSocket or real-time streaming - Use specialized patterns

• Internal microservice communication - When external contracts aren't needed

• Entity modeling - Use humaninloop:patterns-entity-modeling first

• Technical architecture decisions - Use humaninloop:patterns-technical-decisions

Endpoint Mapping

User Action to Endpoint Mapping

User Action HTTP Method Endpoint Pattern

Create resource POST /resources

List resources GET /resources

Get single resource GET /resources/{id}

Update resource PUT/PATCH /resources/{id}

Delete resource DELETE /resources/{id}

Perform action POST /resources/{id}/{action}

Get nested resource GET /resources/{id}/children

Method Selection

Scenario Method Idempotent?

Create new resource POST No

Full replacement PUT Yes

Partial update PATCH No

Read resource GET Yes

Remove resource DELETE Yes

Trigger action POST Usually No

Resource Naming Conventions

• Use plural nouns: /users , not /user

• Use kebab-case for multi-word: /user-profiles

• Use path params for IDs: /users/{userId}

• Use query params for filtering: /users?role=admin

• Use nested paths for relationships: /users/{userId}/tasks

Endpoint Documentation Format

Document each endpoint with description, source requirements, request/response schemas, and error cases:

POST /api/auth/login

Description: Authenticate user with email and password

Source Requirements: FR-001, US#1

Request

{JSON request body example}

Response (200 OK)

{JSON response body example}

Error Responses

Schema Definition

Request Schema Format

LoginRequest: type: object required: - email - password properties: email: type: string format: email description: User's email address password: type: string minLength: 8 description: User's password

Type Mapping from Data Model

Data Model Type OpenAPI Type Format

UUID string uuid

Text string

Email string email

URL string uri

Integer integer int32/int64

Decimal number float/double

Boolean boolean

Timestamp string date-time

Date string date

Enum[a,b,c] string enum: [a,b,c]

Error Response Design

Use standard error format with machine-readable codes and human-readable messages.

See ERROR-PATTERNS.md for complete HTTP status codes, error code conventions, and response formats.

Quick Reference

Status When to Use

400 Invalid input format

401 Missing/invalid auth

403 No permission

404 Resource missing

409 State conflict

422 Business rule violation

429 Rate limit exceeded

500 Server error

List Endpoints

For endpoints returning collections, implement pagination, filtering, and sorting.

See PAGINATION-PATTERNS.md for offset vs cursor pagination, filtering operators, and sorting patterns.

Quick Reference

GET /api/users?page=1&limit=20&role=admin&sort=-createdAt

Brownfield Considerations

When existing API patterns are detected, align new endpoints:

Aspect Check For

Base path /api/v1 , /api , etc.

Auth pattern Bearer, API key, session

Error format Existing error structure

Pagination page/limit, cursor, offset

Handle endpoint collisions:

• REUSE existing endpoints when possible

• RENAME to match existing patterns

• NEW only when no existing endpoint fits

OpenAPI Structure

See OPENAPI-TEMPLATE.yaml for a complete, copy-ready template with all sections.

Minimal Structure

openapi: 3.0.3 info: title: {Feature Name} API version: 1.0.0

servers:

• url: /api

paths: /resource: get: ... post: ...

components: schemas: ... securitySchemes: bearerAuth: type: http scheme: bearer

security:

• bearerAuth: []

Traceability

Track endpoint to requirement mapping:

Endpoint Method FR US Description

/auth/login POST FR-001 US#1 User login

/users/me GET FR-004 US#4 Get current user

Validation

Validate OpenAPI specifications using the validation script:

python scripts/validate-openapi.py path/to/openapi.yaml

Checks: OpenAPI syntax, REST conventions, error responses, request bodies, operation IDs, security schemes, examples, and descriptions.

Quality Checklist

Before finalizing API contracts:

• Every user action has an endpoint

• All endpoints have request schema (if applicable)

• All endpoints have success response schema

• All endpoints have error responses defined

• Naming follows REST conventions

• Authentication requirements documented

• Brownfield patterns matched (if applicable)

• OpenAPI spec is valid

• Traceability to requirements complete

Common Mistakes

Verbs in URLs

❌ /getUsers , /createUser , /deleteUser

✅ /users with appropriate HTTP methods (GET, POST, DELETE)

GET for State-Changing Actions

❌ GET /users/{id}/delete

✅ DELETE /users/{id} or POST /users/{id}/archive

Missing Error Responses

❌ Only documenting 200 OK response ✅ Define all error cases: 400, 401, 403, 404, 409, 422, 500

Inconsistent Naming

❌ Mixing /user-profiles , /userSettings , /user_preferences

✅ Pick one style consistently: /user-profiles , /user-settings , /user-preferences

Generic Error Codes

❌ Just returning 400 or 500 for all errors ✅ Specific codes: INVALID_EMAIL , USER_NOT_FOUND , RATE_LIMIT_EXCEEDED

Missing Examples

❌ Schema definitions without realistic example values ✅ Include example: fields showing real-world data

Skipping Brownfield Check

❌ Creating new patterns when existing API conventions exist ✅ Always check existing API style (auth, error format, pagination) first