К основному содержанию
скилл CX Codex

api-design · yonatangross — скилл для Claude Code: что делает и как установить

Скилл api-design задаёт правила проектирования контрактов REST, GraphQL и gRPC при редактировании эндпоинтов и схем OpenAPI. Включается автоматически при работе с файлами в routes/ и спецификациями.

MIT 211 установок ★ 305 обновлён 2026-11-07

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add yonatangross/orchestkit --skill api-design -a claude-code
Открыть на GitHub

Что делает api-design

Скилл содержит 14 правил в семи категориях: от соглашений REST и схем OpenAPI 3.1 до Strawberry GraphQL и двунаправленных вебсокетов. Он регламентирует структуру URL, пагинацию курсорами, стриминг через SSE с отправкой keepalive каждые 30 секунд и описание ошибок в формате RFC 9457 Problem Details с полями retryable и error_category.

Для версионирования зафиксирована чёткая политика: поддержка текущей и предыдущей версии, оповещение об устаревании минимум за три месяца и полный вывод из эксплуатации через шесть месяцев. При этом скилл отвечает только за архитектуру сетевых контрактов — писать саму бизнес-логику и рабочий код бэкенда разработчики OrchestKit рекомендуют через отдельный скилл python-backend.

Какие задачи решает

  • спроектировать контракт REST-эндпоинта с пагинацией курсорами
  • оформить ошибки API по стандарту RFC 9457 Problem Details
  • составить схему Strawberry GraphQL с защитой от N+1 через DataLoader
  • описать политику версионирования и закрытия устаревших маршрутов

Примеры запросов агенту

  • Спроектируй схему OpenAPI 3.1 для управления заказами с пагинацией по курсору
  • Опиши ответ с ошибкой валидации для эндпоинта /api/v1/users по стандарту RFC 9457
  • Составь контракт эндпоинта со стримингом через SSE и проверкой соединения каждые 30 секунд

Как установить api-design

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/api-design/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об api-design

Как установить api-design в Claude Code?

Запустите команду npx skills add yonatangross/orchestkit --skill api-design -a claude-code. Файл навыка запишется по пути ~/.claude/skills/api-design/SKILL.md.

Что делает скилл api-design?

Он передаёт агенту правила моделирования API: соглашения для путей и параметров, форматы ошибок, спецификации OpenAPI и структуру резолверов GraphQL.

Можно ли генерировать рабочий код бэкенда с помощью этого скилла?

Скилл сфокусирован только на контрактах данных и спецификациях. Для реализации исполняемого серверного кода автор советует подключать python-backend.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →

Сначала — api-design от других авторов.

api-design affaan-m Скилл api-design задаёт правила проектирования REST API: именование эндпоинтов, выбор статус-кодов, пагинацию и формат ошибок. Помогает при создании и ревью серверных контрактов. CX Codex +1 7 500установок api-design Aaronontheweb Скилл api-design для Claude Code и ещё пяти платформ, который задаёт правила проектирования публичных API: только расширять, ничего не ломать. CX Codex +1 702установок api-design margelo Скилл api-design помогает проектировать и проверять публичные API библиотек на TypeScript, JavaScript, React и React Native. CX Codex +1 1 400установок api-design Agent Skills Team Скилл api-design для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode — проектирует или рефакторит контракты REST и GraphQL. Запускается, когда нужно зафиксировать форму API до начала реализации. CX Codex +1 390установок api-design travisjneuman Скилл api-design для Claude Code содержит правила и шаблоны проектирования REST, gRPC и tRPC API, помогает составить спецификацию OpenAPI и упорядочить роуты. CX Codex +1 170установок api-designer https://github.com/Jeffallan Скилл api-designer для архитектуры REST и GraphQL API с генерацией OpenAPI 3.1 спецификаций. Помогает моделировать ресурсы, планировать версионирование и задавать стандарты обработки ошибок. CX Codex +1 7 100установок api-architect curiositech Скилл api-architect помогает проектировать REST, GraphQL и gRPC API: от контракта и схемы до документации и проверки спецификации. CX Codex +1 235установок public-api-design-review Samuel Berthe Скилл public-api-design-review проводит REST API, готовый или ещё на бумаге, по чек-листу из восьми разделов и делит находки на обязательные правки и улучшения. CX Codex +1 10 200установок rest-api-design aj-geddes Скилл rest-api-design задаёт правила именования ресурсов, HTTP-методов, кодов ответа и версионирования, когда вы проектируете новые эндпоинты или переделываете старые. CX Codex +1 2 100установок api-design-reviewer borghei Скилл api-design-reviewer для Claude Code проверяет спецификации OpenAPI, находит несовместимые изменения между версиями и оценивает зрелость контракта REST API. CX Codex +1 167установок api-design-patterns bobmatnyc Скилл api-design-patterns для Claude Code — справочник по архитектуре REST, GraphQL и gRPC; помогает проектировать эндпоинты, пагинацию, версионирование и схемы ошибок. CX Codex +1 585установок

Из того же набора86

Весь набор →
review-pr Скилл review-pr для Claude Code проверяет pull request, ветку или диапазон diff с помощью параллельных агентов. Перед слиянием он выдаёт вердикт approve или request-changes. CX Codex +1 217установок i18n-date-patterns Скилл i18n-date-patterns для Claude Code задаёт агенту правила переводов и локального форматирования в React: языков, дат, валют и сложных форм множественного числа. CX Codex +1 216установок design-system-tokens Скилл design-system-tokens помогает строить W3C-токены для цветов, отступов и тем. Включается при создании .tokens.json и систем с тёмной темой. CX Codex +1 215установок task-dependency-patterns Скилл task-dependency-patterns для Claude Code помогает разбивать сложную работу на задачи и связывать их зависимостями. Он описывает учёт статусов и координацию параллельной работы. CX Codex +1 214установок assess Скилл assess выставляет оценки от 0 до 10 по семи измерениям: правильность, читаемость, сложность, производительность, безопасность, поддерживаемость и соответствие стандартам. CX Codex +1 211установок verify Скилл verify проверяет готовность работы к слиянию: запускает тесты, проверки безопасности и типов, затем даёт оценку от 0 до 10. CX Codex +1 210установок commit Создаёт коммиты в формате Conventional Commits с автоопределением скоупа, строками Co-Authored-By и проверкой хуков; блокирует секреты и сгенерированные файлы. Запускается по команде commit или фразе «сохрани изменения». CX Codex +1 210установок analytics Скилл analytics собирает локальную аналитику вызовов агентов, хуков и токенов из файлов Claude Code. Запускается при проверке расходов и производительности сессий. CX Codex +1 210установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой