api-design

Простым языком

Приложение общается с сервером через специальные адреса — это и есть API. Как правильно их назвать и организовать — целая наука. Этот скилл помогает спроектировать всё грамотно с первого раза.

Скажи Claude что должно делать твоё приложение — и он придумает как будет устроено общение между фронтом и бэком: какие запросы, какие ответы, как защитить от злоупотреблений.

Что делает

Скилл api-design проектирует REST и tRPC API: структуру эндпоинтов, схемы запросов/ответов, коды ошибок, авторизацию, rate limiting. Генерирует OpenAPI-спецификацию и TypeScript-типы.

Claude проектирует API с учётом реальных use cases, а не "для красоты". Каждый эндпоинт обоснован, нет лишних ресурсов.

Когда использовать

• Проектируешь новый сервис или микросервис с нуля
• Нужно задокументировать существующий API
• Добавляешь интеграцию с внешними сервисами (webhook, OAuth)
• Хочешь ревью существующего API на соответствие REST conventions
• Проектируешь API для мобильного приложения

Как работает — пошагово

1. Claude собирает use cases: кто вызывает, с какими данными, что ожидает
2. Проектирует ресурсы: существительные в URL, глаголы через HTTP-методы
3. Определяет схемы запросов и ответов через Zod или TypeScript types
4. Добавляет авторизацию: Bearer JWT, API Key, или session cookies
5. Настраивает rate limiting: разные лимиты для разных эндпоинтов
6. Генерирует OpenAPI 3.0 YAML + TypeScript SDK для клиента

Промпты для Claude

Спроектируй API для системы Q&A:
- Создание вопроса (авторизованный пользователь)
- Список вопросов с фильтрацией по тегам и статусу
- Создание/редактирование ответа
- Принятие ответа как правильного (только автор вопроса)
- Реакции (лайк/дизлайк) с дедупликацией
Стек: Next.js API Routes, Payload CMS, JWT авторизация

Пример дизайна эндпоинтов

# Questions API
GET    /api/questions              # список, ?page=1&tags=react,ts&status=open
POST   /api/questions              # создать (auth required)
GET    /api/questions/:slug        # детали + ответы
PUT    /api/questions/:id          # редактировать (author only)
PATCH  /api/questions/:id/close   # закрыть вопрос (author only)

# Answers
POST   /api/questions/:id/answers  # ответить (auth)
PUT    /api/answers/:id            # редактировать (author, 15min window)
PATCH  /api/answers/:id/accept    # принять ответ (question author)

# Reactions
POST   /api/reactions              # лайк/дизлайк (fingerprint dedup)

Автоматизация

Генерация TypeScript-типов из схем Zod:

// src/lib/api/schemas.ts
import { z } from 'zod'

export const СоздатьВопросSchema = z.object({
  title: z.string().min(10).max(200),
  body: z.string().min(30),
  tags: z.array(z.string()).min(1).max(5),
})

export type СоздатьВопросInput = z.infer<typeof СоздатьВопросSchema>

// Использование в route handler:
const данные = СоздатьВопросSchema.parse(await req.json())

Частые вопросы

REST или tRPC — что выбрать?

tRPC — если фронт и бэк в одном монорепо (Next.js fullstack). Нулевой оверхед, типы из коробки. REST — если нужна интеграция с внешними клиентами или мобилкой.

Как версионировать API?

Для публичных API: /api/v1/, /api/v2/. Для внутренних (только свой фронт) — версионирование не нужно, меняй сразу.