Shapes REST or RPC API surfaces with consistent resource modeling, predictable error responses, paginated list endpoints, and an explicit deprecation policy before implementation locks you into contracts that are costly to change. Good API design prevents client breakage, reduces support burden, and makes feature additions less disruptive.
Use cases
- Designing a greenfield microservice that will be consumed by multiple internal or external clients
- Preparing a public SDK where API stability has legal or business implications
- Planning a breaking change to an existing API and needing to communicate the migration path to clients
- Evaluating whether to use REST, gRPC, or GraphQL for a new service and needing to document the trade-offs
- Adding a new field to an existing response and needing to decide whether it is additive or a breaking change
Key features
- Model the core resources and their relationships before defining endpoints—use a simple entity diagram to validate that the resource model is intuitive for clients
- Define the error response contract with specific error codes, human-readable messages, and machine-readable fields so clients can handle errors programmatically
- Design pagination and filtering contracts for list endpoints, specifying cursor versus offset semantics and maximum page sizes
- Document the versioning strategy: how clients specify API version, how breaking changes are announced, and the sunset timeline for deprecated versions
- Write a short client migration guide for any non-obvious changes before implementing the server, so the contract is validated from the consumer perspective
When to Use This Skill
- When designing a new API from scratch and wanting to avoid common REST design mistakes
- When making breaking changes to an existing API and needing a migration strategy
- When preparing an API for external consumption where you cannot iterate rapidly based on feedback
Expected Output
An API specification document (OpenAPI, Protobuf, or GraphQL schema) with resource models, error contracts, pagination semantics, and a versioning policy.
Frequently Asked Questions
- When should I use path versioning versus header versioning versus query parameter versioning?
- Path versioning (v1, v2 in the URL) is the most explicit and cache-friendly. Header versioning is cleaner but invisible to CDNs and harder to test in browsers. Query parameter versioning is the least preferred and is generally only used for free-tier or legacy APIs.
- How do I avoid breaking changes when adding new fields to responses?
- Adding new optional fields is non-breaking. Adding required fields, removing fields, or changing field types are breaking. Design responses with explicit versioning and treat every change as potentially breaking for strict clients.
- Should I version the API at the service level or the endpoint level?
- Service-level versioning is simpler to manage and is sufficient for most internal services. Endpoint-level versioning (different versions for different endpoints in the same service) adds complexity and is rarely worth it unless individual endpoints have vastly different consumer bases.
Related
Related
3 Indexed items
Designing with LLM structured outputs
This skill covers when and how to ask an LLM for machine-readable payloads: define a JSON Schema (or the vendor's equivalent), enable the structured-output feature your provider documents, validate responses in application code, and handle refusals or validation errors explicitly. It applies to tool-calling agents, extraction pipelines, configuration emitters, and any workflow where brittle text parsing creates production risk.
Agentic workflow design
Structures multi-step agent tasks with explicit inputs, outputs, fallback behavior, and handoff protocols so agents reliably complete complex workflows instead of stopping at the first blocker. Agentic workflow design applies software engineering discipline to AI agent pipelines, treating each step as a function with typed inputs and outputs.
Codebase indexing
Builds and maintains semantic indexes of a codebase so AI coding assistants can retrieve relevant context—file relationships, symbol usage, historical decisions—without re-parsing the entire codebase on every query. Codebase indexing is essential for large codebases where context window limits prevent feeding the entire codebase to the model.