api-design
API contract design for REST and GraphQL, covering resource shape, URL and header versioning with deprecation windows, RFC 9457 Problem Details error handling, and OpenAPI specs. Use when specifying the wire contract an endpoint exposes, choosing a versioning scheme, or standardizing error response bodies across services. Framework-agnostic protocol layer, not runtime implementation.
- Installs
- 203
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/yonatangross/orchestkit --skill api-design- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads api-design automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
API Design
Comprehensive API design patterns covering REST/GraphQL framework design, versioning strategies, and RFC 9457 error handling. Each category has individual rule files in rules/ loaded on-demand.
Quick Reference
| Category | Rules | Impact | When to Use |
|---|---|---|---|
| API Framework | 3 | HIGH | REST conventions, resource modeling, OpenAPI specifications |
| Versioning | 2 | HIGH | URL path versioning, header versioning; deprecation windows are house policy in references/ork-delta.md |
| Error Handling | 1 | HIGH | Agent-facing RFC 9457 extensions; base spec and FastAPI wiring are upstream |
| GraphQL | 2 | HIGH | Strawberry code-first, DataLoader, permissions, subscriptions |
| gRPC | 2 | HIGH | Protobuf services, streaming, interceptors, retry |
| Streaming | 2 | HIGH | SSE endpoints, WebSocket bidirectional, async generators |
| Integrations | 2 | HIGH | Messaging platforms (WhatsApp, Telegram), Payload CMS patterns |
Total: 14 rules across 7 categories. House decisions rescued from thinned files live in references/ork-delta.md; vendor and spec material is linked, not restated (see Upstream coverage).
API Framework
REST and GraphQL API design conventions for consistent, developer-friendly APIs.
| Rule | File | Key Pattern |
|---|---|---|
| REST Conventions | rules/framework-rest-conventions.md | Plural nouns, HTTP methods, status codes, pagination |
| Resource Modeling | rules/framework-resource-modeling.md | Hierarchical URLs, filtering, sorting, field selection |
| OpenAPI | rules/framework-openapi.md | OpenAPI 3.1 specs, documentation, schema definitions |
Versioning
Strategies for API evolution without breaking clients.
| Rule | File | Key Pattern |
|---|---|---|
| URL Path | rules/versioning-url-path.md | /api/v1/ prefix routing, version-specific schemas |
| Header | rules/versioning-header.md | X-API-Version header, content negotiation |
Deprecation and sunset: the house window (3 months notice, 6 months sunset, current + 1 supported) is in references/ork-delta.md; header mechanics are upstream (RFC 8594, RFC 9745).
Error Handling
RFC 9457 Problem Details for machine-readable, standardized error responses.
| Rule | File | Key Pattern |
|---|---|---|
| Agent-Facing Errors | rules/errors-agent-facing.md | Agent extensions: retryable, error_category, content negotiation, token efficiency |
The RFC 9457 base format, FastAPI exception-handler wiring, and Pydantic 422 mapping are upstream (see Upstream coverage). The house pieces survive here: problem type URI convention and typed exception vocabulary in references/ork-delta.md, full working implementation in examples/fastapi-problem-details.md.
GraphQL
Strawberry GraphQL code-first schema with type-safe resolvers and FastAPI integration.
| Rule | File | Key Pattern |
|---|---|---|
| Schema Design | rules/graphql-strawberry.md | Type-safe schema, DataLoader, union errors, Private fields |
| Patterns & Auth | rules/graphql-schema.md | Permission classes, FastAPI integration, subscriptions |
gRPC
High-performance gRPC for internal microservice communication.
| Rule | File | Key Pattern |
|---|---|---|
| Service Definition | rules/grpc-service.md | Protobuf, async server, client timeout, code generation |
| Streaming & Interceptors | rules/grpc-streaming.md | Server/bidirectional streaming, auth, retry backoff |
Streaming
Real-time data streaming with SSE, WebSockets, and proper cleanup.
| Rule | File | Key Pattern |
|---|---|---|
| SSE | rules/streaming-sse.md | SSE endpoints, LLM streaming, reconnection, keepalive |
| WebSocket | rules/streaming-websocket.md | Bidirectional, heartbeat, aclosing(), backpressure |
Integrations
Messaging platform integrations and headless CMS patterns.
| Rule | File | Key Pattern |
|---|---|---|
| Messaging Platforms | rules/messaging-integrations.md | WhatsApp WAHA, Telegram Bot API, webhook security |
| Payload CMS | rules/payload-cms.md | Payload 3.0 collections, access control, CMS selection |
Quick Start Example
# REST endpoint with versioning and RFC 9457 errors
from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse
router = APIRouter()
@router.get("/api/v1/users/{user_id}")
async def get_user(user_id: str, service: UserService = Depends()):
user = await service.get_user(user_id)
if not user:
raise NotFoundProblem(
resource="User",
resource_id=user_id,
)
return UserResponseV1(id=user.id, name=user.full_name)
Key Decisions
| Decision | Recommendation |
|---|---|
| Versioning strategy | URL path (/api/v1/) for public APIs |
| Resource naming | Plural nouns, kebab-case |
| Pagination | Cursor-based for large datasets |
| Error format | RFC 9457 Problem Details with application/problem+json |
| Error type URI | Your API domain + /problems/ prefix |
| Support window | Current + 1 previous version |
| Deprecation notice | 3 months minimum before sunset |
| Sunset period | 6 months after deprecation |
| GraphQL schema | Code-first with Strawberry types |
| N+1 prevention | DataLoader for all nested resolvers |
| GraphQL auth | Permission classes (context-based) |
| gRPC proto | One service per file, shared common.proto |
| gRPC streaming | Server stream for lists, bidirectional for real-time |
| SSE keepalive | Every 30 seconds |
| WebSocket heartbeat | ping-pong every 30 seconds |
| Async generator cleanup | aclosing() for all external resources |
Common Mistakes
- Verbs in URLs (
POST /createUserinstead ofPOST /users) - Inconsistent error formats across endpoints
- Breaking contracts without version bump
- Plain text error responses instead of Problem Details
- Sunsetting versions without deprecation headers
- Exposing internal details (stack traces, DB errors) in errors
- Missing
Content-Type: application/problem+jsonon error responses - Supporting too many concurrent API versions (max 2-3)
- Caching without considering version isolation
Upstream coverage (do not restate)
Topics removed in the 2026-07-31 wrap-plus-delta thinning. Consult the first-party source; only the ork delta (house policy, scars, working config) belongs in this skill.
| Topic | First-party source |
|---|---|
RFC 9457 Problem Details spec (members, media type, about:blank, client parsing) | https://www.rfc-editor.org/rfc/rfc9457.html |
| FastAPI exception handlers, Pydantic validation errors (422), error catalog boilerplate | https://fastapi.tiangolo.com/tutorial/handling-errors/ |
| API versioning strategy tutorials and FastAPI versioned-router walkthroughs | https://fastapi.tiangolo.com/tutorial/bigger-applications/ |
| Deprecation and Sunset header mechanics | https://www.rfc-editor.org/rfc/rfc8594.html and https://www.rfc-editor.org/rfc/rfc9745.html |
| Generic REST reference (methods, status codes, pagination shapes, auth headers) | https://www.rfc-editor.org/rfc/rfc9110.html and https://developer.mozilla.org/en-US/docs/Web/HTTP |
OpenAPI 3.1 spec authoring (template survives in assets/openapi-template.yaml) | https://spec.openapis.org/oas/v3.1.0 |
| gRPC proto style, service definition, status codes | https://grpc.io/docs/ and https://protobuf.dev/programming-guides/style/ |
| Payload CMS collection design, field types, access control | https://payloadcms.com/docs |
| Frontend API consumption (Zod boundary validation, ky, TanStack Query) | https://zod.dev and https://tanstack.com/query/latest/docs |
| API design / error handling / versioning review checklists | Derivable from the specs above; no checklist restatement kept |
Evaluations
See test-cases.json for 13 test cases across all categories.
Related Skills
fastapi-advanced- FastAPI-specific implementation patternsrate-limiting- Advanced rate limiting implementations and algorithmsobservability-monitoring- Version usage metrics and error trackinginput-validation- Validation patterns beyond API error handlingstreaming-api-patterns- SSE and WebSocket patterns for real-time APIs
Capability Details
rest-design
Keywords: rest, restful, http, endpoint, route, path, resource, CRUD Solves:
- How do I design RESTful APIs?
- REST endpoint patterns and conventions
- HTTP methods and status codes
graphql-design
Keywords: graphql, schema, query, mutation, connection, relay Solves:
- How do I design GraphQL APIs?
- Schema design best practices
- Connection pattern for pagination
endpoint-design
Keywords: endpoint, route, path, resource, CRUD, openapi Solves:
- How do I structure API endpoints?
- What's the best URL pattern for this resource?
- RESTful endpoint naming conventions
url-versioning
Keywords: url version, path version, /v1/, /v2/ Solves:
- How to version REST APIs?
- URL-based API versioning
header-versioning
Keywords: header version, X-API-Version, content negotiation Solves:
- Clean URL versioning
- Header-based API version
deprecation
Keywords: deprecation, sunset, version lifecycle, backward compatible Solves:
- How to deprecate API versions?
- Version sunset policy
- Breaking vs non-breaking changes
problem-details
Keywords: problem details, RFC 9457, RFC 7807, structured error, application/problem+json Solves:
- How to standardize API error responses?
- What format for API errors?
agent-facing-errors
Keywords: agent error, AI agent, retryable, retry_after, error_category, content negotiation, accept header, token efficient, machine readable Solves:
- How to design error responses for AI agent consumers?
- How to reduce token cost of error responses?
- How to enable deterministic agent error handling?
- Content negotiation for agents vs browsers vs LLMs
validation-errors
Keywords: validation, field error, 422, unprocessable, pydantic Solves:
- How to handle validation errors in APIs?
- Field-level error responses
error-registry
Keywords: error registry, problem types, error catalog, error codes Solves:
- How to document all API errors?
- Error type management
FAQ
What does the api-design skill do?
API contract design for REST and GraphQL, covering resource shape, URL and header versioning with deprecation windows, RFC 9457 Problem Details error handling, and OpenAPI specs. Use when specifying the wire contract an endpoint exposes, choosing a versioning scheme, or standardizing error response bodies across services. Framework-agnostic protocol layer, not runtime implementation.
How do I install api-design?
Run npx skills add https://github.com/yonatangross/orchestkit --skill api-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/api-design/ (personal) or .claude/skills/api-design/ (project).
Which AI agents can use api-design?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is api-design safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains api-design?
It is published by yonatangross in yonatangross/orchestkit. It has 203 recorded installs.
More from yonatangross/orchestkit
devops-deployment
yonatangross/orchestkit
Use when setting up CI/CD pipelines, containerizing applications, deploying to Kubernetes, or writing infrastructure as code. DevOps & Deployment covers GitHub Actions, Docker, Helm, and Terraform patterns.
responsive-patterns
yonatangross/orchestkit
Responsive design with Container Queries, fluid typography, cqi/cqb units, subgrid, intrinsic layouts, foldable devices, and mobile-first patterns for React applications. Use when building responsive layouts or container queries.
architecture-decision-record
yonatangross/orchestkit
ADR templates in the Nygard format with context, decision, consequences, and alternatives. Use when writing ADRs, recording an architectural decision, or evaluating options.
ui-components
yonatangross/orchestkit
UI component library patterns for shadcn/ui and Radix Primitives. Use when building accessible component libraries, customizing shadcn components, using Radix unstyled primitives, or creating design system foundations.
rag-retrieval
yonatangross/orchestkit
Retrieval-Augmented Generation patterns for grounded LLM responses. Use when building RAG pipelines, embedding documents, implementing hybrid search, contextual retrieval, HyDE, agentic RAG, multimodal RAG, query decomposition, reranking, or pgvector search.
zustand-patterns
yonatangross/orchestkit
Reference for Zustand 5.x state management including slices, middleware, Immer, useShallow, persistence, selectors, and devtools integration. Documents 7 core patterns with TypeScript examples and anti-patterns. Use when building React state management with Zustand instead of Redux.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.