api-contract-design_skill

Overview

This skill helps teams design, document, and evolve REST and GraphQL APIs with practical patterns for contract-first design, versioning, pagination, error handling, and security. It focuses on predictable, discoverable APIs and producing OpenAPI/Swagger specs and GraphQL schemas that developers can implement and trust. Use it to review API contracts, choose versioning and auth strategies, or produce developer-friendly documentation.

How this skill works

The skill inspects API requirements and models resources, operations, and error cases before implementation. It maps REST and GraphQL patterns to concrete artifacts: OpenAPI components, URL/resource models, HTTP status and error payloads, pagination and filtering schemes, and GraphQL types/connections. It also recommends versioning strategies and authentication flows, and validates contracts for consistency and backward compatibility.

When to use it

• Designing a new REST or GraphQL API from the contract outward
• Reviewing or standardizing existing API contracts and docs
• Choosing versioning and deprecation strategies for public APIs
• Specifying authentication and token handling (API keys, OAuth2, JWT)
• Creating OpenAPI/Swagger specifications or GraphQL schemas
• Implementing pagination, filtering, or error formats consistently

Best practices

• Adopt contract-first design so consumers and implementers work in parallel
• Favor consistency: naming, response envelopes, error formats, and date formats (ISO 8601)
• Design for evolution: additive changes only, deprecation windows, and version negotiation
• Use cursor-based pagination for large datasets; offset for simple cases
• Standardize error responses with codes, details, requestId, and documentation links
• Use HTTPS, provide rate-limit headers, and avoid exposing internal implementation details

Example use cases

• Draft an OpenAPI 3.1 spec with reusable components for pagination and errors
• Model REST resource hierarchy and HTTP method semantics for a user/orders domain
• Design GraphQL schema with connections, input types, and payload-based mutations
• Plan an API versioning scheme: major in path, minor via headers, with sunset notices
• Select an authentication approach: API keys for server-to-server, OAuth2 for user flows, JWTs with RS256