Skip to main content
skill CX Codex

api-design · yonatangross — Claude Code skill: what it does, how to install

api-design establishes design standards for REST, GraphQL, and gRPC contracts when editing endpoints or OpenAPI files. Triggers on route definitions and schema changes.

MIT 211 installs ★ 305 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill api-design -a claude-code
Open on GitHub

What api-design does

This skill organizes 14 architectural rules across seven areas, covering REST resource naming, OpenAPI 3.1 definitions, Strawberry GraphQL schemas, and gRPC services. It specifies cursor-based pagination, 30-second keepalives for Server-Sent Events, and RFC 9457 Problem Details with custom agent properties such as retryable and error_category.

Versioning rules enforce strict lifecycles: current plus one previous version, a three-month deprecation warning, and a six-month sunset period. Because the rules focus strictly on wire contracts and interface schemas, writing the actual application runtime logic requires a separate tool like python-backend.

What it helps with

  • design REST contracts with cursor pagination and plural resource paths
  • format API errors using RFC 9457 Problem Details and agent metadata
  • structure Strawberry GraphQL schemas with DataLoaders to avoid N+1 queries
  • define deprecation timelines and sunset headers for public routes

Example prompts for the agent

  • Design an OpenAPI 3.1 schema for order processing with cursor pagination
  • Format a 404 response following RFC 9457 Problem Details for missing items
  • Set up an SSE streaming endpoint contract with 30-second keepalive intervals

How to install api-design

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill api-design -a claude-code

2Manually: put the files in place

~/.claude/skills/api-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-design/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-design

How to install api-design in Claude Code?

Run npx skills add yonatangross/orchestkit --skill api-design -a claude-code. The skill file installs to ~/.claude/skills/api-design/SKILL.md.

What does the api-design skill do?

It instructs AI coding agents on interface design conventions, covering URL structure, OpenAPI schemas, GraphQL types, and standardized error formats.

Does this skill generate backend implementation code?

No, it focuses exclusively on wire contracts and schema definitions. The author recommends using python-backend for writing runtime server code.

Source text

SKILL.md · MIT
---
name: api-design
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "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)."
user-invocable: false
disable-model-invocation: false
metadata:
  owner-agent: "backend-system-architect"
  category: document-asset-creation
  version: "2.0.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "api-design, rest, graphql, versioning, error-handling, rfc9457, openapi, problem-details"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
path_patterns: ["**/routes/**", "**/api/**", "**/endpoints/**", "openapi.*", "swagger.*"]
---

# 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](#api-framework) | 3 | HIGH | REST conventions, resource modeling, OpenAPI specifications |
| [Versioning](#versioning) | 2 | HIGH | URL path versioning, header versioning; deprecation windows are house policy in `references/ork-delta.md` |
| [Error Handling](#error-handling) | 1 | HIGH | Agent-facing RFC 9457 extensions; base spec and FastAPI wiring are upstream |
| [GraphQL](#graphql) | 2 | HIGH | Strawberry code-first, DataLoader, permissions, subscriptions |
| [gRPC](#grpc) | 2 | HIGH | Protobuf services, streaming, interceptors, retry |
| [Streaming](#streaming) | 2 | HIGH | SSE endpoints, WebSocket bidirectional, async generators |
| [Integrations](#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](#upstream-coverage-do-not-restate)).

## 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](#upstream-coverage-do-not-restate)). 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

```python
# 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

1. Verbs in URLs (`POST /createUser` instead of `POST /users`)
2. Inconsistent error formats across endpoints
3. Breaking contracts without version bump
4. Plain text error responses instead of Problem Details
5. Sunsetting versions without deprecation headers
6. Exposing internal details (stack traces, DB errors) in errors
7. Missing `Content-Type: application/problem+json` on error responses
8. Supporting too many concurrent API versions (max 2-3)
9. 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 patterns
- `rate-limiting` - Advanced rate limiting implementations and algorithms
- `observability-monitoring` - Version usage metrics and error tracking
- `input-validation` - Validation patterns beyond API error handling
- `streaming-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

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Backend and APIs →

api-design by other authors comes first.

api-design affaan-m Provides REST API design standards covering resource naming, status codes, pagination, and error payloads. Use it when creating or auditing API contracts. CX Codex +1 7,500installs api-design Aaronontheweb A skill for Claude Code and five other coding agents that enforces extend-only public API design. It activates on signature changes, wire format planning, and pull request reviews where breaking changes are possible. CX Codex +1 702installs api-design margelo The api-design skill shapes and reviews public APIs for TypeScript, JavaScript, React, and React Native libraries before implementation. CX Codex +1 1,400installs api-design Agent Skills Team api-design is a Claude Code skill that designs or refactors REST and GraphQL API contracts. It runs before implementation, while the interface shape is being agreed on. CX Codex +1 390installs api-design travisjneuman api-design is a Claude Code skill with guidelines and templates for REST, gRPC, and tRPC APIs; it helps generate OpenAPI schemas and keep route naming consistent. CX Codex +1 170installs api-designer https://github.com/Jeffallan api-designer — a skill for REST and GraphQL API architecture with OpenAPI 3.1 specification generation. Models resources, plans versioning strategies, and establishes error handling standards. CX Codex +1 7,100installs api-architect curiositech api-architect is a Claude Code skill that guides REST, GraphQL, and gRPC API design, from contracts and schemas to documentation and specification checks. CX Codex +1 235installs public-api-design-review Samuel Berthe public-api-design-review runs a REST API surface, shipped or still on paper, through an eight-part checklist and splits every finding into Must-change or Improvement. CX Codex +1 10,200installs rest-api-design aj-geddes The rest-api-design skill gives your agent rules for resource naming, HTTP methods, status codes and versioning when you build new endpoints or clean up old ones. CX Codex +1 2,100installs api-design-reviewer borghei api-design-reviewer — a skill for Claude Code inspects OpenAPI specs, catches breaking schema changes between versions, and grades REST API architecture maturity. CX Codex +1 167installs api-design-patterns bobmatnyc The api-design-patterns skill for Claude Code is an architectural reference for REST, GraphQL, and gRPC, guiding endpoint structure, pagination, versioning, and error payloads. CX Codex +1 585installs

From the same set86

The whole set →
review-pr review-pr is a Claude Code skill that reviews a pull request, branch, or diff range with parallel agents. It returns an approve or request-changes verdict before a merge. CX Codex +1 217installs i18n-date-patterns i18n-date-patterns guides an agent through React translations and locale-aware formatting. Use it when adding languages, handling dates or currency, or writing pluralized messages. CX Codex +1 216installs design-system-tokens design-system-tokens builds W3C token files for colors, spacing, and themes. It applies while creating .tokens.json files or setting up dark mode. CX Codex +1 215installs task-dependency-patterns task-dependency-patterns is a Claude Code skill for splitting complex work into linked tasks. It covers status tracking and coordination across parallel work. CX Codex +1 214installs assess The assess skill rates code or design decisions 0-10 across seven dimensions: correctness, readability, complexity, performance, security, maintainability and compliance. CX Codex +1 211installs verify verify is a skill that checks whether work is ready to merge by running tests, security and type checks, then assigns a 0–10 score. CX Codex +1 210installs commit Creates Conventional Commits with scope detection, Co-Authored-By trailers and pre-commit checks; blocks secrets and generated files. Runs on commit or “save my changes”. CX Codex +1 210installs analytics analytics queries local Claude Code logs to report agent usage, hook latency, and token expenses. Runs whenever you inspect session costs or runtime bottlenecks. CX Codex +1 210installs

Project sponsors

Companies that keep this analytics open