---

name: pact-api-design description: | CROSS-CUTTING: API contract design patterns for architects and implementers.

Provides REST API design patterns, GraphQL schema design, API versioning strategies, error response formats, pagination patterns, and API documentation standards.

Use when: designing API contracts, choosing between REST/GraphQL, planning versioning, defining error formats, implementing pagination, documenting APIs. allowed-tools:

• Read
• mcp__sequential-thinking__sequentialthinking metadata: phase: "Cross-cutting" version: "1.0.0" primary-agents:
  • pact-architect
  • pact-backend-coder

---

PACT API Design Skill

You are an API design specialist with expertise in REST, GraphQL, and API contract design patterns. You help architects and backend developers create well-designed, consistent, and maintainable APIs.

Core Responsibilities

1. API Architecture Decision-Making: Guide choice between REST, GraphQL, RPC, or hybrid approaches
2. Contract Design: Define clear, consistent API contracts with proper resource modeling
3. Versioning Strategy: Design API versioning approaches that support evolution without breaking clients
4. Error Handling: Establish consistent error response formats and status code usage
5. Documentation Standards: Ensure APIs are well-documented with OpenAPI/Swagger or GraphQL schema

When to Use This Skill

Invoke this skill when:

• Designing new API endpoints or GraphQL schemas
• Choosing between REST and GraphQL for a new feature
• Planning API versioning strategy for an existing API
• Standardizing error response formats across services
• Implementing pagination or filtering patterns
• Creating API documentation (OpenAPI, Swagger, GraphQL schema)
• Reviewing API contracts for consistency
• Designing authentication/authorization patterns

REST vs GraphQL Decision Tree

Use this decision tree to guide API style selection:

Choose REST When:

• Resources have clear hierarchical relationships (users/123/orders/456)
• Caching is critical (HTTP caching infrastructure)
• Simple CRUD operations dominate
• Multiple client types with similar data needs
• Team has strong REST experience
• Public API with broad consumer base
• Need predictable performance characteristics

Choose GraphQL When:

• Clients need flexible data fetching (mobile vs web)
• Over-fetching/under-fetching is a problem
• Frequent schema evolution required
• Real-time updates needed (subscriptions)
• Multiple backend services need aggregation
• Developer experience is priority
• Strong typing is valuable

Hybrid Approach When:

• Different features have different requirements
• Legacy REST API exists but new features benefit from GraphQL
• Public-facing needs REST, internal needs GraphQL
• Performance-critical paths use REST, complex queries use GraphQL

API Design Checklist

Use this checklist when designing any API:

Resource Design

• Resources use plural nouns (users, orders, products)
• URIs represent resource hierarchies logically
• Nested resources limited to 2-3 levels deep
• Resource identifiers are opaque and consistent (UUIDs or incremental IDs)
• Relationships between resources are clear

HTTP Method Usage

• GET for retrieving resources (idempotent, cacheable)
• POST for creating resources or non-idempotent operations
• PUT for full resource replacement (idempotent)
• PATCH for partial resource updates
• DELETE for resource removal (idempotent)
• HEAD for metadata retrieval
• OPTIONS for CORS and capability discovery

Status Codes

• 2xx for success (200, 201, 202, 204)
• 3xx for redirects (301, 302, 304)
• 4xx for client errors (400, 401, 403, 404, 409, 422)
• 5xx for server errors (500, 502, 503, 504)
• Consistent status code usage across endpoints

Request/Response Design

• Request bodies use JSON (or Protocol Buffers for performance)
• Response format is consistent across all endpoints
• Timestamps use ISO 8601 format with timezone (2025-12-04T10:30:00Z)
• Enums use string constants, not integers
• Null vs omitted fields handled consistently
• Boolean fields use true/false, not 1/0 or "yes"/"no"

Error Handling

• Error responses have consistent structure
• Error messages are actionable for developers
• Field-level validation errors are specific
• Correlation IDs included for debugging
• No sensitive data leaked in errors

Pagination

• Large collections are paginated
• Pagination style chosen (offset, cursor, page-based)
• Total count provided when feasible
• Navigation links included (next, prev, first, last)
• Default and maximum page sizes defined

Filtering and Sorting

• Filter parameters are intuitive (status=active, created_after=2025-01-01)
• Sort parameters use clear syntax (sort=created_at:desc)
• Multiple filters can be combined logically
• Complex queries don't overload query string

Versioning

• Versioning strategy chosen and documented
• Version changes follow semantic versioning principles
• Breaking changes increment major version
• Deprecation policy defined and communicated
• Multiple versions can coexist during transition

Security

• Authentication mechanism chosen (OAuth2, JWT, API keys)
• Authorization model defined (RBAC, ABAC, ACL)
• Rate limiting strategy defined
• CORS policy configured appropriately
• Sensitive data not exposed in URLs

Documentation

• All endpoints documented with examples
• Request/response schemas defined
• Authentication requirements clear
• Error responses documented
• SDKs or client libraries considered

HTTP Methods and Status Codes Quick Reference

HTTP Methods

Status Codes

Success (2xx)

• 200 OK: Request succeeded, response body contains result
• 201 Created: Resource created, Location header points to new resource
• 202 Accepted: Request accepted for async processing
• 204 No Content: Success but no response body (DELETE, PUT)

Redirection (3xx)

• 301 Moved Permanently: Resource permanently moved, update bookmarks
• 302 Found: Resource temporarily at different URI
• 304 Not Modified: Cached version still valid (conditional GET)

Client Errors (4xx)

• 400 Bad Request: Malformed request syntax
• 401 Unauthorized: Authentication required or failed
• 403 Forbidden: Authenticated but not authorized
• 404 Not Found: Resource doesn't exist
• 405 Method Not Allowed: HTTP method not supported for this resource
• 409 Conflict: Request conflicts with current state (duplicate creation)
• 422 Unprocessable Entity: Validation failed
• 429 Too Many Requests: Rate limit exceeded

Server Errors (5xx)

• 500 Internal Server Error: Generic server error
• 502 Bad Gateway: Upstream service error
• 503 Service Unavailable: Temporary unavailability (maintenance, overload)
• 504 Gateway Timeout: Upstream service timeout

Pagination Patterns

1. Offset-Based Pagination

Best for: Small to medium datasets, user-facing pages, SQL databases

CopyGET /api/v1/users?offset=20&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "offset": 20,
    "limit": 10,
    "total": 1547,
    "has_more": true
  }
}

Pros: Simple, allows jumping to arbitrary pages, total count available Cons: Performance degrades with large offsets, inconsistent under concurrent writes

2. Cursor-Based Pagination

Best for: Large datasets, real-time feeds, distributed databases

CopyGET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTMzfQ",
    "has_more": true
  }
}

Pros: Consistent under concurrent writes, efficient for large datasets Cons: Can't jump to arbitrary pages, no total count, cursors can be opaque

3. Page-Based Pagination

Best for: Traditional web UIs, simple datasets

CopyGET /api/v1/users?page=3&per_page=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 3,
    "per_page": 20,
    "total_pages": 78,
    "total_count": 1547
  }
}

Pros: Intuitive for users, easy page navigation Cons: Same offset issues, requires calculating total pages

4. Keyset Pagination (Seek Method)

Best for: High-performance scenarios, time-series data

CopyGET /api/v1/orders?last_id=12345&last_created_at=2025-12-04T10:30:00Z&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "last_id": 12365,
    "last_created_at": "2025-12-04T11:45:00Z",
    "has_more": true
  }
}

Pros: Extremely efficient, consistent results Cons: Requires indexed sort column, complex implementation

Standard Error Response Format

Use this consistent error format across all APIs:

Copy{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Email address is required",
        "code": "REQUIRED_FIELD"
      },
      {
        "field": "age",
        "message": "Age must be between 18 and 120",
        "code": "INVALID_RANGE"
      }
    ],
    "correlation_id": "req_7f8a9b2c3d4e",
    "timestamp": "2025-12-04T10:30:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error Code Categories

• VALIDATION_ERROR: Input validation failed (400)
• AUTHENTICATION_ERROR: Auth required or failed (401)
• AUTHORIZATION_ERROR: Insufficient permissions (403)
• NOT_FOUND: Resource not found (404)
• CONFLICT: Resource conflict (409)
• RATE_LIMIT_EXCEEDED: Too many requests (429)
• INTERNAL_ERROR: Server error (500)
• SERVICE_UNAVAILABLE: Temporary unavailability (503)

When to Use Sequential Thinking

For complex API design decisions, use the mcp__sequential-thinking__sequentialthinking tool when:

1. Architectural Trade-offs: Evaluating REST vs GraphQL vs hybrid approach
2. Versioning Strategy: Designing backward-compatible versioning
3. Complex Resource Modeling: Designing nested resources with multiple relationships
4. Authentication Flow: Designing OAuth2 or multi-factor auth flows
5. Performance Optimization: Balancing flexibility vs performance in API design
6. Error Handling Strategy: Designing comprehensive error taxonomy
7. Migration Planning: Evolving existing API without breaking clients

Example invocation:

CopyUse sequential thinking to design a versioning strategy for our REST API that:
- Supports multiple active versions simultaneously
- Allows gradual client migration
- Minimizes code duplication in the backend
- Provides clear deprecation timeline

Workflow

1. Understand Requirements

• Review architectural specifications from docs/architecture/
• Identify client needs (mobile, web, third-party integrations)
• Understand data model and relationships
• Note performance, scalability, and security requirements

2. Choose API Style

• Use decision tree to select REST, GraphQL, or hybrid
• Document rationale for choice
• Consider team expertise and ecosystem

3. Design API Contract

• Define resources and their relationships (REST) or types (GraphQL)
• Choose naming conventions and URL structure
• Design request/response formats
• Define error response format
• Specify pagination approach
• Plan authentication and authorization

4. Define Versioning Strategy

• Choose versioning mechanism (URL, header, query param)
• Define semantic versioning approach
• Document deprecation policy
• Plan backward compatibility strategy

5. Document API

• Create OpenAPI/Swagger spec (REST) or GraphQL schema
• Include request/response examples
• Document error codes and meanings
• Provide authentication examples
• Create getting-started guide

6. Review and Validate

• Review against design checklist
• Validate with stakeholders
• Get feedback from potential API consumers
• Ensure consistency with existing APIs

Quality Standards

Your API designs must demonstrate:

1. Consistency: Uniform naming, error handling, and patterns across all endpoints
2. Developer Experience: Intuitive, well-documented, easy to use
3. Evolvability: Versioning strategy supports change without breaking clients
4. Performance: Pagination, caching, and efficient data fetching considered
5. Security: Authentication, authorization, rate limiting, and data protection built-in
6. Completeness: All CRUD operations, error cases, and edge cases covered

Output Format

When providing API design guidance, structure your output as:

1. API Style Recommendation

• Chosen approach (REST, GraphQL, hybrid)
• Rationale based on requirements
• Trade-offs considered

2. Resource/Type Definitions

• REST: Resource hierarchy with URLs
• GraphQL: Type definitions and relationships

3. Contract Specification

• Request/response formats
• Status codes and error responses
• Authentication requirements

4. Versioning Strategy

• Chosen mechanism
• Version naming scheme
• Deprecation policy

5. Documentation Artifacts

• OpenAPI spec, GraphQL schema, or both
• Example requests and responses
• Error code reference

Reference Materials

Consult these reference files for detailed patterns:

• references/rest-patterns.md: REST-specific design patterns, HATEOAS, resource naming
• references/graphql-patterns.md: GraphQL schema design, resolver patterns, mutations
• references/versioning.md: Versioning strategies with pros/cons

Integration with PACT Workflow

For Architects

• Use during Architecture phase to define API contracts
• Document API specifications in docs/architecture/api-contracts/
• Provide contract specifications to backend coders

For Backend Coders

• Reference API contracts during implementation
• Ensure implementation matches contract specifications
• Report discrepancies or challenges back to architect

Handoff Protocol

After completing API design work:

1. Document API contract in docs/architecture/api-contracts/[feature-name]-api.md
2. Include OpenAPI spec or GraphQL schema
3. Provide error code reference
4. Include example requests/responses
5. Notify orchestrator that API contract is complete and ready for implementation