api-design

API Design

Help the user design RESTful APIs with consistent patterns, clear contracts, and proper error handling.

Process

1. Identify resources - What are the nouns/entities the API exposes?
2. Define operations - What CRUD and custom operations are needed?
3. Design the URL structure - Map resources to RESTful endpoints
4. Specify request/response schemas - Define the contract for each endpoint
5. Plan versioning - How will the API evolve without breaking consumers?
6. Document with OpenAPI - Create the specification before implementing

All APIs at Imagine Learning follow REST conventions and must have an OpenAPI spec before implementation begins.

RESTful Conventions

IL API Conventions

• Content type: application/json for all request and response bodies
• Base URLs: Services are typically exposed via host-based routing (each service on its own subdomain); path-based routing is used when we want to share a domain across multiple APIs
• Required headers: Tracing headers (W3C Trace Context or B3) for distributed tracing; correlationId for structured log correlation
• Timeouts: Target response time under 500ms for synchronous endpoints

URL Structure

GET    /api/v1/{resource}          # List resources
POST   /api/v1/{resource}          # Create resource
GET    /api/v1/{resource}/{id}     # Get resource by ID
PUT    /api/v1/{resource}/{id}     # Replace resource
PATCH  /api/v1/{resource}/{id}     # Partial update
DELETE /api/v1/{resource}/{id}     # Delete resource

Naming Rules

• Use plural nouns for resource names (/users, not /user)
• Use kebab-case for multi-word resources (/learning-paths)
• Use camelCase for JSON field names
• Nest sub-resources for relationships (/users/{id}/enrollments)

Synchronous vs Asynchronous API Patterns

Not all API operations should be handled in the request/response cycle. When designing endpoints, decide whether the operation should complete synchronously or be offloaded to async processing.

Synchronous (respond immediately):

• Reads and queries — caller is waiting for data
• Simple writes where the caller needs confirmation (create, update, delete)
• Validation and authorization checks

Asynchronous (accept and process later):

• Long-running operations (export generation, bulk imports, report building)
• Operations whose downstream side effects don't need immediate feedback (grade rollup recalculation, LMS sync, notification delivery, Caliper event emission)
• Anything where the caller just needs to know the request was accepted, not that all downstream work is complete

Async API Pattern: Accept-and-Queue

For async operations, use 202 Accepted to acknowledge the request, then process the work via events:

POST /api/v1/sections/{sectionId}/export
→ 202 Accepted
→ { "exportId": "EXP-001", "status": "pending", "statusUrl": "/api/v1/exports/EXP-001" }

The caller can poll the status URL or receive a notification when processing completes.

When to Defer to Events

If an operation triggers work that is a consequence of the primary action — and the caller doesn't need to wait for that work to finish — the API should persist the primary data synchronously and let downstream processing happen asynchronously via events. Refer to the eventing-architect agent for event flow design.

Versioning Strategy

IL uses URL path versioning (/v1/resources, /v2/resources) as the standard. Explicit, discoverable in API docs, and easy to route.

Strategy	Pros	Cons
URL path (/v1/)	Explicit, easy to route	URL pollution
Header (Accept-Version)	Clean URLs	Harder to test/discover
Query param (?version=1)	Easy to add	Easily forgotten

Increment version only for breaking changes: removing a field, changing a field type, altering behavior of an existing endpoint. Additive changes (new optional fields, new endpoints) do not require a version bump.

Error Handling

Use RFC 7807 Problem Details as the standard error response format:

Standard error:

{
  "type": "https://api.imaginelearning.com/problems/resource-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "No user exists with ID '12345'",
  "instance": "/v1/users/12345",
  "traceId": "abc-123-def-456"
}

Validation error (multiple fields):

{
  "type": "https://api.imaginelearning.com/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request body contains invalid fields",
  "errors": [
    { "field": "email", "message": "Must be a valid email address" },
    { "field": "birthDate", "message": "Must not be in the future" }
  ],
  "traceId": "abc-123-def-456"
}

HTTP Status Code Usage

Code	Usage
200	Successful GET, PUT, PATCH
201	Successful POST (resource created)
202	Accepted — async operation queued for processing
204	Successful DELETE (no content)
400	Validation error, malformed request
401	Authentication required
403	Authenticated but not authorized
404	Resource not found
409	Conflict (duplicate, state conflict)
422	Semantically invalid request
429	Rate limit exceeded
500	Internal server error

Request and Response Standards

Standard Response Envelope:

• List endpoints: { "data": [...], "pagination": { ... } }
• Single-resource endpoints: return the resource directly (no envelope)

Required Request Headers:

Header	Value	Purpose
Content-Type	application/json	Request body format
Accept	application/json	Expected response format
traceparent	W3C Trace Context	Distributed tracing propagation

Tracing and Correlation:

• Propagate W3C Trace Context headers (traceparent, tracestate) or B3 headers on all outbound requests
• Include correlationId in structured logs for every request
• Cross-reference the observability skill for full tracing and logging guidance

Pagination

Prefer cursor-based pagination for new APIs. Stable under concurrent writes, performs well at scale, avoids offset consistency issues. Use offset-based only when consumers need arbitrary page jumps (admin/reporting UIs over small, stable datasets).

Standard query parameters: cursor (opaque string), limit (default 25, max 100).

Cursor-Based (Preferred for large datasets)

{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTAwfQ==",
    "hasMore": true
  }
}

Offset-Based (For smaller, stable datasets)

{
  "data": [...],
  "pagination": {
    "offset": 0,
    "limit": 25,
    "total": 142
  }
}

Contract-First Development

OpenAPI Specification

1. Write the OpenAPI spec before writing code — the spec is the source of truth
2. Share the spec with consumers (frontend teams, other services) for review before implementation
3. Generate server stubs and client SDKs from the spec where tooling supports it
4. Validate requests and responses against the spec in tests

OpenAPI conventions:

• Use OpenAPI 3.0+ (YAML format preferred for readability)
• Define reusable schemas in components/schemas — avoid inline definitions
• Include example values for all request/response bodies
• Document all error responses using the RFC 7807 Problem Details schema
• Tag endpoints by resource for logical grouping
• Include description on all operations, parameters, and schema properties

Consumer-Driven Contract Testing (Pact)

• Use Pact for contract testing between frontend and backend, and between services
• Consumer defines the expected interactions (request/response pairs) it depends on
• Provider verifies it can satisfy all consumer contracts as part of CI
• Contracts are versioned and shared via a Pact Broker
• Run provider verification on every PR — broken contracts block merge
• When adding a new endpoint: consumer writes the contract first, provider implements to satisfy it

API Documentation

Documentation requirements:

• Every API must have a published OpenAPI spec accessible to consumers
• Include a README or developer guide covering: authentication requirements, common workflows, and error handling
• Document rate limits, pagination defaults, and any non-obvious behavior

Deprecation process:

• Mark deprecated endpoints with deprecated: true in the OpenAPI spec
• Return a Sunset header with the planned removal date on deprecated endpoints
• Communicate deprecation timeline via team channels — minimum 2 release cycles before removal
• Remove deprecated endpoints only on a major version bump

Related Skills and Agents

Topic	Where to Go
Language and framework selection for backend	backend-architect agent
Caching and Cache-Control headers	caching skill
Logging, tracing, and SLOs	observability skill
DynamoDB data modeling for API-backed resources	dynamodb-table-design skill
Micro-frontend BFF patterns	mfe-architecture skill, frontend-architect agent
Service deployment and Kubernetes configuration	backend-architect agent

Checklist

Before publishing an API:

• OpenAPI spec is complete and reviewed
• All endpoints follow RESTful conventions
• Error responses use RFC 7807 Problem Details format
• Pagination is implemented for list endpoints
• Authentication and authorization are enforced
• Rate limiting is configured
• Request validation returns helpful error messages
• API versioning strategy is applied
• Tracing headers (W3C Trace Context or B3) are propagated on all outbound calls
• Pact consumer contracts are defined and provider verification runs in CI
• Deprecated endpoints include Sunset header and are marked in the OpenAPI spec