Agent skill · software engineering · yonatangross
api-design
API wire contracts for REST and GraphQL: resource shape, versioning and deprecation, RFC 9457 errors, OpenAPI. Use when designing an endpoint contract. Not for runtime code (use python-backend).
Why this skill is useful
Provides specific patterns for API design, versioning strategies, and error handling that the AI wouldn't reliably generate on its own.
What it needs
About 6k tokens when loaded. Last updated 2026-08-06. 215 stars on the source repository.
What this skill does
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). …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills yonatangross/api-design