pact-api-design

REST and GraphQL represent different architectural approaches to API design. REST uses standard HTTP methods on resource endpoints, while GraphQL allows clients to query exactly the data they need through a single endpoint. Choose REST for simple, resource-oriented domains and GraphQL for complex queries with variable client needs. This Skill guides you through decision criteria for each approach based on your requirements.

API versioning strategies minimize disruption during evolution. Common approaches include URL versioning, header-based versioning, and deprecation windows with clear timelines. Design a versioning strategy upfront by defining how you'll signal changes, maintain backward compatibility, and communicate deprecation schedules. This Skill helps you architect versioning and deprecation plans that keep clients stable.

Standardized error formats improve client integration and debugging. Define consistent error schemas that include status codes, error messages, and actionable details. Apply the same structure across all endpoints so clients can handle failures predictably. This Skill provides patterns for designing error handling formats that work across REST and GraphQL APIs.

OpenAPI (Swagger) and GraphQL schemas serve different documentation needs. OpenAPI works best for REST APIs, generating interactive documentation from structured specifications. GraphQL includes schema introspection built-in, enabling self-documenting APIs and tooling. This Skill covers both documentation standards and helps you choose or combine them based on your API design.

Pagination patterns control data returned per request and improve performance. Common patterns include offset/limit pagination, cursor-based pagination for consistency across changes, and keyset pagination for scalability. Design your pagination strategy early to ensure consistent behavior across endpoints. This Skill includes established pagination patterns applicable to REST and GraphQL APIs.

API contracts define the interface between client and server through resource models, naming conventions, and schema specifications. Document contracts using OpenAPI, GraphQL schemas, or similar specifications before coding to align teams early. This Skill helps you draft initial contracts and documentation that serve as implementation blueprints and client references.