🔌 Core Philosophy: APIs are contracts; once published, they are hard to break.
When to use
Use this skill when designing web endpoints, data exchange schemas, error structures, rate-limiting frameworks, pagination, and SDK interfaces.
When not to use
Do not use this skill for frontend state management, local storage layout, or layout styling.
Trigger cues
- Key terms: REST, RESTful, API, OpenAPI, Swagger, GraphQL, gRPC, tRPC, endpoint, schema, request/response, versioning, URL structure, HTTP status, JSON API, payload.
- Designing API specs, designing microservices interaction, defining payload models.
Routing boundary
- Primary for network protocol schemas, RESTful constraints, serialization definitions, and API evolutionary practices.
- Secondary to
developer-web-security for authentication protocols.
Inputs required
- Target protocol requirements (REST, GraphQL, gRPC, etc.)
- Scalability requirements and pagination targets
- Source of truth:
references/source.md
Instructions
- Detect Stack: Inspect the workspace files to identify the project's existing technology stack (e.g., Next.js, FastAPI, Express, Django).
- Do Not Migrate: Never propose or force a technology stack change. Apply the principles in this skill using the project's current tooling.
- Read references/source.md to understand contract-first API design.
- Draft API endpoints using OpenAPI (REST) or schema definitions (GraphQL) matching the project's tooling.
- Standardize error formats using RFC 7807 problem details.
- Define clear query filters, sorting, and cursor-based pagination parameters.
Completion gate
Before reporting completion, verify the applicable binary contracts in evals/cases.json: RFC 7807 errors, bounded cursor pagination with explicit filtering and sorting, and a contract expressed in the project's existing API stack.
Output format
- Primary decision/output: API Endpoint specifications, JSON schema definition, and versioning rules.
- Summary: One-paragraph API design overview.
- Actions: Verification checklist for HTTP compatibility, error robustness, and pagination standards.
1---2name: api-design-guidelines3description: Trigger: REST API, GraphQL schemas, HTTP methods, RFC 7807, endpoint structure, API contracts. Scope: API schema design, error models, request/response structures. Boundary: Excludes client-side visual layouts.4---56# 🔌 Core Philosophy: APIs are contracts; once published, they are hard to break.78## When to use910Use this skill when designing web endpoints, data exchange schemas, error structures, rate-limiting frameworks, pagination, and SDK interfaces.1112## When not to use1314Do not use this skill for frontend state management, local storage layout, or layout styling.1516## Trigger cues1718- Key terms: REST, RESTful, API, OpenAPI, Swagger, GraphQL, gRPC, tRPC, endpoint, schema, request/response, versioning, URL structure, HTTP status, JSON API, payload.19- Designing API specs, designing microservices interaction, defining payload models.2021## Routing boundary2223- Primary for network protocol schemas, RESTful constraints, serialization definitions, and API evolutionary practices.24- Secondary to `developer-web-security` for authentication protocols.2526## Inputs required2728- Target protocol requirements (REST, GraphQL, gRPC, etc.)29- Scalability requirements and pagination targets30- Source of truth: `references/source.md`3132## Instructions33341. **Detect Stack**: Inspect the workspace files to identify the project's existing technology stack (e.g., Next.js, FastAPI, Express, Django).352. **Do Not Migrate**: Never propose or force a technology stack change. Apply the principles in this skill using the project's current tooling.363. Read [references/source.md](references/source.md) to understand contract-first API design.374. Draft API endpoints using OpenAPI (REST) or schema definitions (GraphQL) matching the project's tooling.385. Standardize error formats using RFC 7807 problem details.396. Define clear query filters, sorting, and cursor-based pagination parameters.4041## Completion gate4243Before reporting completion, verify the applicable binary contracts in `evals/cases.json`: RFC 7807 errors, bounded cursor pagination with explicit filtering and sorting, and a contract expressed in the project's existing API stack.4445## Output format4647- Primary decision/output: API Endpoint specifications, JSON schema definition, and versioning rules.48- Summary: One-paragraph API design overview.49- Actions: Verification checklist for HTTP compatibility, error robustness, and pagination standards.
coreyone