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

api-design-expert — скилл для Claude Code: REST, GraphQL, версии API

Скилл api-design-expert для проектирования HTTP API: ресурсы REST, выбор между GraphQL и gRPC, схемы версионирования и единый формат ошибок. Полезен до того, как написан первый эндпоинт.

Apache-2.0 180 установок ★ 45 обновлён 2026-10-12

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

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

Скилл подключается сам, когда в задаче всплывают REST, GraphQL, версии API или безопасность API. Агенту он даёт рабочую рамку: ресурсно-ориентированный REST, другие стили вроде gRPC, WebSocket и server-sent events, а поверх — версионирование, аутентификация, лимиты запросов и совместимость со старыми клиентами.

Примеры внутри на Python. Приложение на FastAPI с моделями Pydantic показывает списочные методы с пагинацией и сортировкой, вложенные ресурсы и три способа версионирования: в пути (/api/v1), через заголовок API-Version и через content negotiation. Отдельно разобраны обработчики исключений, которые сводят ошибки валидации и бизнес-ошибки к одному телу ответа.

Вот тут и ограничение: стек примеров — FastAPI и Pydantic, так что для Express, Spring или Go шаблоны придётся переносить руками. Скилл задаёт форму, а не генерирует код под любой фреймворк. Разрешённых инструментов три: Read, Write и Edit — файлы читает и правит, а тесты не запускает.

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

  • Разложить ресурсы и эндпоинты REST-сервиса до написания обработчиков
  • Выбрать схему версионирования: путь, заголовок или content negotiation
  • Свести ошибки валидации и бизнес-ошибки к одному формату ответа
  • Взвесить REST против GraphQL или gRPC для нового сервиса
  • Добавить пагинацию и сортировку в списочные методы

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

  • Спроектируй REST API для заказов: ресурсы, методы, коды ответов, версия в пути /api/v1
  • Сравни REST и GraphQL для нашего сервиса и объясни, что выбрать
  • Перепиши ответы с ошибками так, чтобы у всех были одинаковые поля

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

1Через Skills CLI (Vercel)

npx skills add personamanagmentlayer/pcl --skill api-design-expert -a claude-code

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

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

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

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

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

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

Выполните npx skills add personamanagmentlayer/pcl --skill api-design-expert -a claude-code. Файл скилла появится по пути ~/.claude/skills/api-design-expert/SKILL.md.

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

Подсказывает агенту, как устроить HTTP API: ресурсы, методы, версионирование, коды ошибок, аутентификация и лимиты. Включается по упоминанию REST, GraphQL, версий API или безопасности API.

Нужен ли FastAPI, чтобы им пользоваться?

Примеры кода написаны на Python с FastAPI и Pydantic. Для другого фреймворка структуру и решения придётся переносить вручную.

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

SKILL.md · Apache-2.0
---
name: api-design-expert
version: 1.1.0
description: >-
  Expert-level API design principles, REST, GraphQL, versioning, and API best practices.
  Use when the user mentions REST, GraphQL, API versioning, or API security, or when the
  task involves API Design Principles, API Styles, or Documentation.
category: api
tags: [api-design, rest, graphql, api-versioning, api-security]
allowed-tools:
  - Read
  - Write
  - Edit
---

# API Design Expert

Expert guidance for API design, RESTful principles, GraphQL, versioning strategies, and API best practices.

## Core Concepts

### API Design Principles

- RESTful architecture
- Resource-oriented design
- Uniform interface
- Statelessness
- Cacheability
- Layered system

### API Styles

- REST (Representational State Transfer)
- GraphQL
- RPC (Remote Procedure Call)
- WebSocket
- Server-Sent Events (SSE)
- gRPC

### Key Considerations

- Versioning strategies
- Authentication and authorization
- Rate limiting
- Error handling
- Documentation
- Backward compatibility

## REST API Design

```python
from fastapi import FastAPI, HTTPException, Query, Path, Header
from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime
from enum import Enum

app = FastAPI(
    title="User Management API",
    version="1.0.0",
    description="RESTful API for user management"
)

# Models
class UserRole(str, Enum):
    ADMIN = "admin"
    USER = "user"
    GUEST = "guest"

class UserCreate(BaseModel):
    email: str = Field(..., example="[email protected]")
    name: str = Field(..., min_length=1, max_length=100)
    role: UserRole = UserRole.USER

class UserResponse(BaseModel):
    id: str
    email: str
    name: str
    role: UserRole
    created_at: datetime
    updated_at: datetime

    class Config:
        schema_extra = {
            "example": {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "email": "[email protected]",
                "name": "John Doe",
                "role": "user",
                "created_at": "2024-01-01T00:00:00Z",
                "updated_at": "2024-01-01T00:00:00Z"
            }
        }

class UserUpdate(BaseModel):
    name: Optional[str] = Field(None, min_length=1, max_length=100)
    role: Optional[UserRole] = None

# REST Endpoints following best practices
@app.get("/api/v1/users",
         response_model=List[UserResponse],
         summary="List all users",
         tags=["Users"])
async def list_users(
    page: int = Query(1, ge=1, description="Page number"),
    page_size: int = Query(20, ge=1, le=100, description="Items per page"),
    sort: str = Query("created_at", description="Sort field"),
    order: str = Query("desc", regex="^(asc|desc)$")
):
    """
    Retrieve a paginated list of users.

    - **page**: Page number (starts at 1)
    - **page_size**: Number of items per page (1-100)
    - **sort**: Field to sort by
    - **order**: Sort order (asc or desc)
    """
    # Implementation
    return []

@app.get("/api/v1/users/{user_id}",
         response_model=UserResponse,
         summary="Get user by ID",
         tags=["Users"])
async def get_user(
    user_id: str = Path(..., description="User ID")
):
    """Retrieve a specific user by ID."""
    # Implementation
    raise HTTPException(status_code=404, detail="User not found")

@app.post("/api/v1/users",
          response_model=UserResponse,
          status_code=201,
          summary="Create new user",
          tags=["Users"])
async def create_user(user: UserCreate):
    """Create a new user."""
    # Implementation
    return UserResponse(
        id="123e4567-e89b-12d3-a456-426614174000",
        email=user.email,
        name=user.name,
        role=user.role,
        created_at=datetime.now(),
        updated_at=datetime.now()
    )

@app.patch("/api/v1/users/{user_id}",
           response_model=UserResponse,
           summary="Update user",
           tags=["Users"])
async def update_user(
    user_id: str = Path(..., description="User ID"),
    user: UserUpdate = None
):
    """Partially update a user."""
    # Implementation
    pass

@app.delete("/api/v1/users/{user_id}",
            status_code=204,
            summary="Delete user",
            tags=["Users"])
async def delete_user(
    user_id: str = Path(..., description="User ID")
):
    """Delete a user."""
    # Implementation
    pass

# Nested resources
@app.get("/api/v1/users/{user_id}/posts",
         summary="Get user posts",
         tags=["Users", "Posts"])
async def get_user_posts(user_id: str):
    """Retrieve all posts for a specific user."""
    return []
```

## API Versioning

```python
from fastapi import APIRouter, Request

# URL Path Versioning (Recommended)
v1_router = APIRouter(prefix="/api/v1")
v2_router = APIRouter(prefix="/api/v2")

@v1_router.get("/users")
async def get_users_v1():
    """Version 1: Returns basic user info"""
    return [{"id": 1, "name": "John"}]

@v2_router.get("/users")
async def get_users_v2():
    """Version 2: Returns enhanced user info"""
    return [{"id": 1, "name": "John", "email": "[email protected]"}]

# Header Versioning
async def version_from_header(request: Request):
    version = request.headers.get("API-Version", "1")
    return version

@app.get("/api/users")
async def get_users(version: str = Depends(version_from_header)):
    if version == "2":
        return get_users_v2()
    return get_users_v1()

# Content Negotiation Versioning
@app.get("/api/users")
async def get_users_content_negotiation(
    accept: str = Header("application/vnd.api+json; version=1")
):
    if "version=2" in accept:
        return get_users_v2()
    return get_users_v1()
```

## Error Handling

```python
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from pydantic import BaseModel, ValidationError

class ErrorResponse(BaseModel):
    error: str
    message: str
    details: Optional[dict] = None
    timestamp: datetime
    path: str

@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content=ErrorResponse(
            error=exc.status_code,
            message=exc.detail,
            timestamp=datetime.now(),
            path=request.url.path
        ).dict()
    )

@app.exception_handler(ValidationError)
async def validation_exception_handler(request: Request, exc: ValidationError):
    return JSONResponse(
        status_code=422,
        content=ErrorResponse(
            error="validation_error",
            message="Request validation failed",
            details=exc.errors(),
            timestamp=datetime.now(),
            path=request.url.path
        ).dict()
    )

# Custom business logic errors
class BusinessError(Exception):
    def __init__(self, message: str, code: str):
        self.message = message
        self.code = code

@app.exception_handler(BusinessError)
async def business_error_handler(request: Request, exc: BusinessError):
    return JSONResponse(
        status_code=400,
        content=ErrorResponse(
            error=exc.code,
            message=exc.message,
            timestamp=datetime.now(),
            path=request.url.path
        ).dict()
    )
```

## Rate Limiting

```python
from fastapi import Request, HTTPException
from datetime import datetime, timedelta
import redis
from typing import Dict

class RateLimiter:
    def __init__(self, redis_client: redis.Redis):
        self.redis = redis_client

    async def check_rate_limit(self,
                               key: str,
                               max_requests: int,
                               window_seconds: int) -> Dict:
        """
        Token bucket algorithm for rate limiting
        """
        now = datetime.now().timestamp()
        window_key = f"rate_limit:{key}:{int(now // window_seconds)}"

        pipe = self.redis.pipeline()
        pipe.incr(window_key)
        pipe.expire(window_key, window_seconds)
        result = pipe.execute()

        request_count = result[0]

        if request_count > max_requests:
            reset_time = (int(now // window_seconds) + 1) * window_seconds
            raise HTTPException(
                status_code=429,
                detail="Rate limit exceeded",
                headers={
                    "X-RateLimit-Limit": str(max_requests),
                    "X-RateLimit-Remaining": "0",
                    "X-RateLimit-Reset": str(reset_time)
                }
            )

        return {
            "limit": max_requests,
            "remaining": max_requests - request_count,
            "reset": (int(now // window_seconds) + 1) * window_seconds
        }

# Middleware for rate limiting
@app.middleware("http")
async def rate_limit_middleware(request: Request, call_next):
    limiter = RateLimiter(redis_client)

    # Get client identifier (IP, API key, etc.)
    client_id = request.client.host

    try:
        rate_info = await limiter.check_rate_limit(
            client_id,
            max_requests=100,
            window_seconds=60
        )

        response = await call_next(request)

        # Add rate limit headers
        response.headers["X-RateLimit-Limit"] = str(rate_info["limit"])
        response.headers["X-RateLimit-Remaining"] = str(rate_info["remaining"])
        response.headers["X-RateLimit-Reset"] = str(rate_info["reset"])

        return response
    except HTTPException as e:
        return JSONResponse(
            status_code=e.status_code,
            content={"error": e.detail},
            headers=e.headers
        )
```

## HATEOAS Implementation

```python
from typing import Dict, List

class HATEOASResponse(BaseModel):
    data: dict
    links: Dict[str, str]

def create_links(resource_id: str, resource_type: str) -> Dict[str, str]:
    """Create HATEOAS links for a resource"""
    return {
        "self": f"/api/v1/{resource_type}/{resource_id}",
        "update": f"/api/v1/{resource_type}/{resource_id}",
        "delete": f"/api/v1/{resource_type}/{resource_id}",
        "collection": f"/api/v1/{resource_type}"
    }

@app.get("/api/v1/users/{user_id}", response_model=HATEOASResponse)
async def get_user_with_links(user_id: str):
    user = get_user_from_db(user_id)

    return HATEOASResponse(
        data=user,
        links={
            "self": f"/api/v1/users/{user_id}",
            "posts": f"/api/v1/users/{user_id}/posts",
            "profile": f"/api/v1/users/{user_id}/profile",
            "update": f"/api/v1/users/{user_id}",
            "delete": f"/api/v1/users/{user_id}"
        }
    )
```

## API Security

```python
import os

from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from jose import JWTError, jwt
from passlib.context import CryptContext

security = HTTPBearer()
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

# The JWT signing key. A literal here means every deployment that copies
# this file shares a forgeable key - load it, and fail closed if absent.
SECRET_KEY = os.environ["JWT_SECRET_KEY"]
ALGORITHM = "HS256"

async def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
    """Verify JWT token"""
    try:
        payload = jwt.decode(
            credentials.credentials,
            SECRET_KEY,
            algorithms=[ALGORITHM]
        )
        return payload
    except JWTError:
        raise HTTPException(
            status_code=401,
            detail="Invalid authentication credentials"
        )

@app.get("/api/v1/protected")
async def protected_route(token_payload: dict = Depends(verify_token)):
    return {"message": "Access granted", "user": token_payload}

# API Key Authentication
async def verify_api_key(api_key: str = Header(...)):
    """Verify API key"""
    if api_key not in valid_api_keys:
        raise HTTPException(status_code=403, detail="Invalid API key")
    return api_key
```

## Best Practices

### Design

- Use nouns for resources, not verbs
- Use plural names for collections
- Use HTTP methods correctly (GET, POST, PUT, PATCH, DELETE)
- Return appropriate status codes
- Support filtering, sorting, and pagination
- Use consistent naming conventions
- Version APIs from the start

### Documentation

- Use OpenAPI/Swagger
- Provide example requests and responses
- Document error codes and messages
- Include authentication requirements
- Keep documentation up-to-date
- Provide SDKs when possible

### Performance

- Implement caching (ETags, Cache-Control)
- Support compression (gzip)
- Paginate large result sets
- Use async operations for long tasks
- Implement rate limiting
- Monitor API performance

### Security

- Use HTTPS always
- Implement authentication and authorization
- Validate all inputs
- Rate limit to prevent abuse
- Log security events
- Use API keys or OAuth 2.0
- Implement CORS properly

## Anti-Patterns

❌ Using GET for state-changing operations
❌ Returning inconsistent response formats
❌ No versioning strategy
❌ Poor error messages
❌ No rate limiting
❌ Exposing internal implementation details
❌ Breaking changes without versioning

## Resources

- REST API Design Best Practices: https://restfulapi.net/
- OpenAPI Specification: https://swagger.io/specification/
- API Design Guide: https://cloud.google.com/apis/design
- Microsoft REST API Guidelines: https://github.com/microsoft/api-guidelines
- FastAPI: https://fastapi.tiangolo.com/

© personamanagmentlayer · Apache-2.0 · personamanagmentlayer/pcl

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

Все скиллы по теме «Бэкенд и 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-rate-limit-policy Samuel Berthe Скилл api-rate-limit-policy для Claude Code, Codex, Cursor и других агентов, который проектирует политику rate limit публичного API: модели измерения трафика, квоты по тирам, заголовки и поведение 429. CX Codex +1 10 400установок public-api-design-review Samuel Berthe Скилл public-api-design-review проводит REST API, готовый или ещё на бумаге, по чек-листу из восьми разделов и делит находки на обязательные правки и улучшения. CX Codex +1 10 200установок api-and-interface-design addyosmani Скилл api-and-interface-design помогает проектировать API и границы модулей так, чтобы их было проще использовать и менять. Подходит для REST, GraphQL и публичных интерфейсов. CX Codex +1 79 800установок api-design-principles Seth Hobson Скилл api-design-principles помогает проектировать и проверять REST- и GraphQL API. Пригодится при подготовке спецификации, пересмотре существующего API или согласовании стандартов команды. CX Codex +1 30 348установок api-design-patterns bobmatnyc Скилл api-design-patterns для Claude Code — справочник по архитектуре REST, GraphQL и gRPC; помогает проектировать эндпоинты, пагинацию, версионирование и схемы ошибок. CX Codex +1 585установок

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

Весь набор →
istio-expert Скилл istio-expert для Claude Code настраивает трафик, mTLS и наблюдаемость в Istio для Kubernetes. Диагностирует mesh и помогает готовить политики доступа. CX Codex +1 184установок grpc-expert Скилл grpc-expert разбирает gRPC-сервисы: схемы Protocol Buffers, четыре вида RPC, коды ошибок и продакшн-обвязку вроде балансировки и health checking. CX Codex +1 182установок media-expert Скилл media-expert для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode, который добавляет агенту экспертизу в медиапроизводстве, стриминге и вещании. CX Codex +1 182установок microservices-expert Скилл microservices-expert для Claude Code помогает проектировать микросервисную архитектуру, обмен между сервисами и распределённые операции. Разбирает задачи с service mesh и отказами. CX Codex +1 181установок azure-expert Скилл azure-expert помогает проектировать архитектуру в Microsoft Azure, писать код для Azure Functions и Cosmos DB, а также генерировать команды Azure CLI. CX Codex +1 180установок dbt-expert Скилл dbt-expert для Claude Code помогает проектировать dbt-модели, тесты, документацию, макросы и Jinja-шаблоны. Решает задачи аналитической инженерии и SQL-преобразований. CX Codex +1 180установок rust-expert Скилл rust-expert для Claude Code задаёт ИИ-агенту роль Rust-разработчика: владение, лайфтаймы, async и обработка ошибок. Разбирает неочевидные ошибки borrow checker. CX Codex +1 179установок design-expert Скилл design-expert даёт агенту паттерны системного дизайна, масштабирования и распределённых систем с готовыми примерами кода на Python. CX Codex +1 178установок

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

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