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

designing-apis — скилл для Claude Code: REST и GraphQL

Скилл designing-apis в Claude Code проектирует REST и GraphQL API: структурирует эндпоинты, описывает форматы запросов и ответов, настраивает обработку ошибок и версионирование.

MIT ★ 1 424 обновлён 2026-10-06

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflow
Открыть на GitHub

Что делает designing-apis

Скилл работает в Claude Code и содержит чек-лист проектирования на семь шагов: от определения ресурсов до валидации дизайна. Для REST предлагает стандартные URL-структуры (GET /users/:id, POST /users), таблицу кодов ответов (200, 201, 400, 401, 404, 429 и прочие) и примеры структур для успешных, ошибочных и пагинированных ответов. Для GraphQL показывает, как писать типы запросов, мутаций и входные схемы.

Внутри также есть паттерны аутентификации (JWT, API-ключи), заголовки rate limiting, шаблон OpenAPI-спецификации и список проверок безопасности (HTTPS, валидация входа, CORS, отсутствие чувствительных данных в URL).

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

  • спроектировать REST API с правильной структурой эндпоинтов и кодами ответов
  • определить схему GraphQL с типами, мутациями и входными параметрами
  • описать версионирование API и стратегию обновления
  • настроить обработку ошибок, аутентификацию и rate limiting
  • валидировать API-дизайн перед реализацией

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

  • Спроектируй REST API для сервиса учёта заказов с фильтрацией и пагинацией
  • Покажи, как организовать GraphQL-схему для пользователей и их заказов
  • Проверь мой API-контракт на соответствие best practices: эндпоинты, коды ошибок, аутентификация

Как установить designing-apis

1Через маркетплейс плагинов

/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflow

Команда ставит плагин project-starter целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

npx skills add CloudAI-X/claude-workflow-v2 --skill designing-apis -a claude-code

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

~/.claude/skills/designing-apis/SKILL.md

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

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

Вопросы о designing-apis

Как установить designing-apis в Claude Code?

Выполни /plugin marketplace add CloudAI-X/claude-workflow-v2, затем /plugin install project-starter@claude-workflow. После этого запусти npx skills add CloudAI-X/claude-workflow-v2 --skill designing-apis -a claude-code. Скилл будет доступен в ~/.claude/skills/designing-apis/SKILL.md.

Что делает скилл designing-apis?

Помогает спроектировать API: определяет структуру эндпоинтов, форматы запросов и ответов, коды ошибок, версионирование, аутентификацию и правила rate limiting. Охватывает REST и GraphQL, включает чек-листы проектирования и безопасности.

Чем отличается REST от GraphQL в контексте этого скилла?

REST использует URL-эндпоинты и HTTP-методы (GET, POST, PUT, DELETE); GraphQL — единую точку входа с типами запросов и мутаций. Скилл показывает оба подхода: для REST — структуру путей и коды ответов, для GraphQL — схемы типов и входные параметры.

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

SKILL.md · MIT
---
name: designing-apis
description: Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation. Use when creating new APIs, designing endpoints, reviewing API contracts, or when asked about REST, GraphQL, or API patterns.
---

# Designing APIs

### When to Load

- **Trigger**: Designing REST or GraphQL endpoints, API contracts, versioning, request/response formats
- **Skip**: Internal-only code with no API surface

## API Design Workflow

Copy this checklist and track progress:

```
API Design Progress:
- [ ] Step 1: Define resources and relationships
- [ ] Step 2: Design endpoint structure
- [ ] Step 3: Define request/response formats
- [ ] Step 4: Plan error handling
- [ ] Step 5: Add authentication/authorization
- [ ] Step 6: Document with OpenAPI spec
- [ ] Step 7: Validate design against checklist
```

## REST API Design

### URL Structure

```
# Resource-based URLs (nouns, not verbs)
GET    /users              # List users
GET    /users/:id          # Get user
POST   /users              # Create user
PUT    /users/:id          # Replace user
PATCH  /users/:id          # Update user
DELETE /users/:id          # Delete user

# Nested resources
GET    /users/:id/orders   # User's orders
POST   /users/:id/orders   # Create order for user

# Query parameters for filtering/pagination
GET    /users?role=admin&status=active
GET    /users?page=2&limit=20&sort=-createdAt
```

### HTTP Status Codes

| Code | Meaning           | Use Case                   |
| ---- | ----------------- | -------------------------- |
| 200  | OK                | Successful GET, PUT, PATCH |
| 201  | Created           | Successful POST            |
| 204  | No Content        | Successful DELETE          |
| 400  | Bad Request       | Invalid input              |
| 401  | Unauthorized      | Missing/invalid auth       |
| 403  | Forbidden         | Valid auth, no permission  |
| 404  | Not Found         | Resource doesn't exist     |
| 409  | Conflict          | Duplicate, state conflict  |
| 422  | Unprocessable     | Validation failed          |
| 429  | Too Many Requests | Rate limited               |
| 500  | Internal Error    | Server error               |

### Response Formats

**Success Response:**

```json
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  },
  "meta": {
    "requestId": "abc-123"
  }
}
```

**List Response with Pagination:**

```json
{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=5"
  }
}
```

**Error Response:**

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  },
  "meta": {
    "requestId": "abc-123"
  }
}
```

## API Versioning

**URL Versioning (Recommended):**

```
/api/v1/users
/api/v2/users
```

**Header Versioning:**

```
Accept: application/vnd.example.v1+json
```

## Authentication Patterns

**JWT Bearer Token:**

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

**API Key:**

```
X-API-Key: your-api-key
```

## Rate Limiting Headers

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200
Retry-After: 60
```

## GraphQL Patterns

**Schema Design:**

```graphql
# Abbreviated: input, connection and error types omitted for brevity
type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: Pagination): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): UserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UserPayload!
}

type User {
  id: ID!
  name: String!
  email: String!
  orders(first: Int, after: String): OrderConnection!
}

input CreateUserInput {
  name: String!
  email: String!
}

type UserPayload {
  user: User
  errors: [Error!]
}
```

## OpenAPI Specification Template

See [OPENAPI-TEMPLATE.md](OPENAPI-TEMPLATE.md) for the full OpenAPI 3.0 specification template.

## API Design Validation

After completing the design, validate against this checklist:

```
Validation Checklist:
- [ ] All endpoints use nouns, not verbs
- [ ] HTTP methods match operations correctly
- [ ] Consistent response format across endpoints
- [ ] Error responses include actionable details
- [ ] Pagination implemented for list endpoints
- [ ] Authentication defined for protected endpoints
- [ ] Rate limiting headers documented
- [ ] OpenAPI spec is complete and valid
```

If validation fails, return to the relevant design step and address the issues.

## Security Checklist

- [ ] HTTPS only
- [ ] Authentication on all endpoints
- [ ] Authorization checks
- [ ] Input validation
- [ ] Rate limiting
- [ ] Request size limits
- [ ] CORS properly configured
- [ ] No sensitive data in URLs
- [ ] Audit logging

© CloudAI-X · MIT · CloudAI-X/claude-workflow-v2

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

Все скиллы по теме «Бэкенд и API» →
api-design Agent Skills Team Скилл api-design для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode — проектирует или рефакторит контракты REST и GraphQL. Запускается, когда нужно зафиксировать форму API до начала реализации. CX Codex +1 390установок api-designer https://github.com/Jeffallan Скилл api-designer для архитектуры REST и GraphQL API с генерацией OpenAPI 3.1 спецификаций. Помогает моделировать ресурсы, планировать версионирование и задавать стандарты обработки ошибок. CX Codex +1 7 100установок discover-api rand Скилл discover-api подключает специализированные знания об API-дизайне, аутентификации и авторизации автоматически, когда вы работаете с REST, GraphQL или вопросами безопасности. Экономит время на переключение между гайдами. CX Codex +1 113установок rest-api-design-patterns manutej Скилл rest-api-design-patterns для Claude Code помогает проектировать и приводить к единому виду REST API: моделировать ресурсы, версионирование, пагинацию, HATEOAS и HTTP-методы. CX Codex +1 527установок 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установок

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

Весь набор →
plan Создаёт и ведёт файл PLAN.md в корне проекта для фиксации этапов разработки, зависимостей между задачами и лога прогресса. CX Codex +1 ★ 1 424звёзд репо refactor-guided Команда refactor-guided проводит структурный рефакторинг по шагам и проверяет тесты после каждого изменения. Подходит для безопасной перестройки кода без добавления функций. CX Codex +1 ★ 1 424звёзд репо convex-backend Скилл convex-backend загружает guidelines для работы с Convex: функции, схемы, валидаторы, queries, mutations, actions, подписки и хранилище файлов. Помогает писать типобезопасный бэкенд на TypeScript. CX Codex +1 ★ 1 424звёзд репо dependency-upgrade Команда dependency-upgrade для Claude Code поочерёдно обновляет зависимости, запускает тесты после каждого пакета и откатывает изменения при ошибках. CX Codex +1 ★ 1 424звёзд репо parallel-analyze Команда parallel-analyze запускает четыре субагента разом: архитектура, безопасность, производительность и тесты. Сводит их находки в один отчёт с приоритетами. CX Codex +1 ★ 1 424звёзд репо managing-git Скилл managing-git помогает Claude Code вести ветки по GitHub Flow или Git Flow, оформлять коммиты по Conventional Commits и готовить пулл-реквесты по чек-листам. CX Codex +1 ★ 1 424звёзд репо code-reviewer Субагент code-reviewer для Claude, который читает изменённые файлы и выдаёт разбор по severity: логика, безопасность, производительность, тесты. CX Codex ★ 1 424звёзд репо designing-architecture Скилл designing-architecture для Claude Code помогает выбрать архитектурный паттерн, оценить размер проекта и команды и структурировать код. Включается при проектировании системы и принятии архитектурных решений. CX Codex +1 ★ 1 424звёзд репо

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

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