API, который не заставит фронтенд гадать

Проектируем REST, GraphQL и gRPC API. Продуманные контракты, типовая безопасность, документация и версионирование. Фронт и бэк говорят на одном языке.

Когда нужно проектировать API

API нужен не всегда. Но когда нужен — без него никак

Фронтенд отдельно от бэкенда

Две команды или два подрядчика. API — это контракт, который нельзя нарушать.

Мобильное приложение + сайт

Один бэкенд — много клиентов. API должен быть одинаково удобен для всех.

Открытое API для сторонних разработчиков

Вы даёте доступ к своим данным. API должен быть понятным, безопасным и стабильным.

Микросервисная архитектура

Сервисы общаются между собой через API. Без чётких контрактов всё развалится.

Интеграция с партнёрами

Партнёры забирают данные или отправляют заказы. API — это граница вашей системы.

Сложные сценарии запросов

Клиенту нужны не все данные, а только часть. GraphQL или фильтры REST решают проблему.

REST, GraphQL или gRPC? Выбираем под задачу

REST — классика и простота. GraphQL — гибкость и один эндпоинт. gRPC — скорость и типизация. Мы выбираем не то, что модно, а то, что решит вашу задачу без боли.

REST

Ресурсный подход, HTTP-методы, кэширование
Идеально для публичных API, простых сценариев
Понятно всем. Кэширование на уровне CDN

Оптимально для: простоты и совместимости

подробнее подробнее

GraphQL

Один эндпоинт, клиент сам выбирает поля
Идеально для сложных выборок, дашбордов, мобильных приложений
Клиент не перегружает сеть лишними данными

Оптимально для: гибкости и экономии трафика

подробнее подробнее

gRPC

Высокая производительность, HTTP/2, protobuf
Идеально для внутренних сервисов, микросервисов, highload
В 10 раз быстрее JSON. Строгая типизация

Оптимально для: скорости и надёжности

подробнее подробнее

Подберём API под ваш проект

REST, GraphQL или gRPC — решение зависит от того, кто будет использовать API: только ваш фронт, мобильное приложение, партнёры или внутренние сервисы.

Оставьте контакты — и мы предложим подход, который не придётся переделывать через полгода.

ПОлучить консультацию ПОлучить консультацию

Этапы проектирования API

Анализ сценариев

от 1–2 дней

Кто будет использовать API: только ваш фронт, мобильное приложение, партнёры или внутренние сервисы? Какие сценарии самые частые, а какие самые сложные? Что критично по скорости, а что может подождать?

Результат:

список сценариев с приоритетами и требованиями к производительности.

Ответственные:

аналитик, архитектор.

Проектирование ресурсов

от 1–2 дней

Какие сущности есть в системе? Пользователи, заказы, товары, платежи. Как они связаны между собой? Как их правильно назвать, чтобы было понятно и фронту, и бэку?

Результат:

ресурсная модель — сущности, поля, связи.

Ответственные:

архитектор, бэкенд-разработчик.

Выбор подхода

от 1 дня

REST, GraphQL или gRPC? Под сценарии, а не под тренды. REST — для простоты и публичных API. GraphQL — для сложных выборок и мобильных приложений. gRPC — для высокой скорости и внутренних сервисов.

Результат:

выбранный подход с обоснованием

Ответственные:

архитектор, техлид.

Контракт и документация

от 2–3 дней

OpenAPI-спецификация для REST, Schema для GraphQL, protobuf для gRPC. Документация генерируется из кода — всегда свежая. Фронт и бэк согласовали контракт до того, как написан первый запрос.

Результат:

API-контракт + документация (Swagger / GraphQL Playground)

Ответственные:

бэкенд-разработчик, фронтенд-разработчик.

Версионирование

от 1 дня

API будет меняться — это факт. Старые клиенты не должны падать. /v1, /v2 в URL, заголовок Accept-Version или совместимые изменения без смены версии. Выбираем стратегию и документируем.

Результат:

принятая стратегия версионирования + первый эндпоинт с версией

Ответственные:

архитектор, бэкенд-разработчик.

Мониторинг и аналитика

от 1–2 дней

Какие эндпоинты реально используются? Какие долгие? Какие падают? Собираем метрики, логи, настраиваем алерты. Знаем состояние API в реальном времени.

Результат:

настроенный мониторинг + дашборд с ключевыми метриками

Ответственные:

DevOps, бэкенд-разработчик.

API не терпит ошибок в начале

Неправильный подход к проектированию API аукнется через полгода: переписывание контрактов, падающий фронт, недовольные партнёры.
Оставьте контакты — мы разберём ваши сценарии и предложим подход, который не придётся переделывать.

Из чего складывается хороший API

Ресурсная модель

Что у нас есть? Пользователи, заказы, товары. Каждый ресурс — свой эндпоинт.

HTTP-методы

GET — получить, POST — создать, PUT/PATCH — обновить, DELETE — удалить. Без сюрпризов.

Статус коды

200 — ок, 201 — создано, 400 — плохой запрос, 404 — не найдено. Понятно без документации.

Валидация

Плохие данные не попадают в базу. Ошибка валидации — понятное сообщение.

Аутентификация

JWT, OAuth, API-ключи. Кто ты и есть ли у тебя доступ.

Rate Limiting

1000 запросов в минуту — достаточно. Не даём себя положить.

Мониторинг

Сколько запросов, какие долгие, какие падают. Знаем состояние API в реальном времени.

Почему API часто болит

Как делают «для галочки»

Как делаем мы

API родилось само собой в процессе разработки

Проектируем API до кода. Контракт готов — можно пилить параллельно

Документация в голове у разработчика

OpenAPI / Swagger. Документация всегда свежая и доступна

Нет версионирования — обновление API ломает фронт

Версионирование с рождения. Старые клиенты не падают

Ошибка 500 — и никто не знает, что произошло

Понятные статус-коды + human-readable сообщение

API отдаёт всё подряд — фронт тонет в данных

Только то, что запросили. Фильтры, пагинация, выбор полей

Нет rate limiting — один бот положил весь сервис

Rate limiting на каждый эндпоинт. Сервер жив

Без мониторинга — о падениях узнаём от клиентов

Логи, метрики, алерты. Упало — мы знаем первыми

Расскажите о проекте — спроектируем API

Кто будет использовать API: только ваш фронт, мобильное приложение, партнёры или внутренние сервисы? Какие сценарии самые частые и самые сложные?
Прикрепите ТЗ или просто напишите словами — мы предложим архитектуру API до созвона.