API дизайн

Проектирование API — это дисциплина определения контрактов, эндпоинтов и шаблонов взаимодействия, позволяющих программным системам надёжно и эффективно общаться между собой. Хорошо спроектированный REST API следует модели зрелости Ричардсона — от базовой идентификации ресурсов через HTTP до корректного использования методов GET, POST, PUT, PATCH и DELETE вплоть до полноценных HATEOAS hypermedia-элементов управления, — тогда как GraphQL API используют строго типизированную схему, описанную в SDL, предоставляя клиентам точный контроль над получаемыми данными. Хорошее проектирование API требует выбора правильного протокола: REST и GraphQL поверх HTTP/1.1 или HTTP/2 для веб-клиентов, gRPC с Protocol Buffers для высоконагруженных микросервисов, WebSocket — для двунаправленных каналов в реальном времени. Единообразие тоже важно: стандартизированные конверты ошибок (RFC 7807 Problem Details), соглашения о пагинации (cursor, offset/limit) и стратегия версионирования (префикс /v1/ в URL или заголовок Accept-Version) снижают трудозатраты для потребителей API. Безопасность должна быть заложена в проект с самого начала: эндпоинты следует защищать JWT-токенами или скоупами OAuth 2.0, маскировать чувствительные поля и применять ограничение частоты запросов с помощью заголовков вроде X-RateLimit-Remaining.

Как это работает

API дизайн имеет три доминирующих стиля: REST (resource-oriented, использует HTTP-семантику, легко кешируется), GraphQL (клиент выбирает форму, один endpoint, хорошо для разных клиентов), gRPC/RPC (вызов процедур, строгая схема, низкий overhead). Хороший API предсказуем: консистентные имена, версионирован (/v1/users), пагинация для коллекций (курсор лучше offset), фильтруем, идемпотентен где безопасно, задокументирован (OpenAPI для REST, .proto для gRPC, schema для GraphQL).

Когда применять

REST — для публичных API, которые потребляет много третьих сторон: lowest common denominator. GraphQL — когда один backend обслуживает много форм клиента (web + iOS + Android с разными нуждами) и хотите избежать bespoke endpoint на клиента. gRPC — для internal service-to-service, где важны latency + типизированные контракты. Микс ок: публичный REST + internal gRPC — частый кейс.

Типичные ошибки

Ловушки API дизайн: нет версионирования ("добавим версию потом" — к тому моменту breaking change для всех); глубоко вложенные ресурсы (/users/123/orders/456/items/789 — плоский лучше); chatty API (клиент делает 10 вызовов на одну страницу — батчите или expand related); утечка внутренних ID (auto-increment integer выдаёт объём — UUID лучше); непоследовательный формат ошибок. Пишите доки API так, будто их прочитает незнакомец.

Связанные понятия

• REST API и Richardson Maturity
• GraphQL
• gRPC
• OpenAPI и Swagger