API (Application Programming Interface) — это «клей» между вашим сайтом, мобильным приложением, чат-ботом и внешними сервисами. Плохо спроектированный API приводит к тому, что:
- Приложение тормозит (потому что API отдаёт слишком много лишних данных).
- Разработка новой фичи занимает в 3 раза дольше.
- Через год вы вынуждены переписывать API полностью, ломая обратную совместимость со старыми клиентами.
В этой статье — основные принципы проектирования хорошего API. Независимо от того, делаете вы API для сайта с React на фронте или мобильного приложения, эти правила универсальны.
RESTful — стандарт де-факто (но не догма)
Большинство современных API строятся по принципам REST (Representational State Transfer). Это набор правил, которые делают API понятным и предсказуемым.
Ключевые принципы REST:
- Ресурсо-ориентированность. Всё, с чем вы работаете — это ресурсы (users, orders, products).
-
Использование HTTP-методов по назначению:
- GET — получение ресурса (не должен ничего менять).
- POST — создание нового ресурса.
- PUT / PATCH — обновление ресурса.
- DELETE — удаление ресурса.
- Использование HTTP-статусов: 200 — OK, 201 — Created, 400 — Bad Request, 401 — Unauthorized, 403 — Forbidden, 404 — Not Found, 422 — Unprocessable Entity, 500 — Internal Server Error.
- Человекопонятные URL (без глаголов): /users/123/orders, а не /getUserOrders?id=123.
REST — это хорошая отправная точка для 90% проектов. Если вам нужно что-то более производительное или специфичное — смотрите в сторону GraphQL или gRPC.
Версионирование API: не ломайте клиентов
Одна из самых частых ошибок — когда новую версию API запускают на тех же URL, что и старую, и старые клиенты (мобильные приложения, которые не обновили) перестают работать.
Правильные способы версионирования:
- Через URL: /v1/users, /v2/users. Самый простой и наглядный.
- Через заголовок Accept: Accept: application/vnd.myapi.v1+json. Чище, но сложнее для отладки.
- Через кастомный заголовок: X-API-Version: 1.
Золотое правило: Старую версию поддерживайте как минимум 6-12 месяцев после выхода новой, чтобы дать клиентам время на обновление.
Форматы данных: JSON (почти всегда) и документация
Используйте JSON. XML и другие форматы — в прошлом (если только к вам не приходят запросы от древних систем).
Правила хорошего JSON:
- Используйте snake_case для полей (user_id, first_name).
- Даты в ISO 8601 (2025-03-13T14:30:00Z).
- Не возвращайте null, если можно не возвращать поле вообще. Или возвращайте null осознанно.
- Для пагинации используйте стандарт: ?page=2&limit=20, а в ответе возвращайте { data, total, page, total_pages }.
Документация — MUST HAVE. Без документации ваше API бесполезно. Используйте инструменты, которые генерируют документацию автоматически:
- Swagger / OpenAPI. Стандарт индустрии. По описанию можно сгенерировать SDK на любом языке.
- Postman Collections. Можно документировать прямо в Postman и делиться.
- API Blueprint, Slate, Readme.io.
Документация должна содержать: примеры запросов и ответов, описание возможных ошибок (статусы + коды ошибок), ограничения (rate limits), аутентификацию (как получить токен).
Безопасность: базовая, но без дыр
- API работает ТОЛЬКО по HTTPS. Никакого HTTP.
- Аутентификация через токены (JWT или Bearer Token). Не передавайте логин-пароль на каждый запрос. Получили токен — используйте его в заголовке Authorization: Bearer .
- Ограничение частоты запросов (Rate Limiting). Для авторизованных пользователей: 1000 запросов в час. Для неавторизованных: 100 в час. Это защищает от DDoS и брутфорса.
- Валидируйте все входные данные на стороне сервера. Не доверяйте клиенту. Даже если клиент — ваше приложение.
- Никогда не возвращайте пользователю внутренние ошибки с трейсами (500). Только обобщённое «Internal Server Error», а подробности в логи сервера.
Производительность: что нужно знать
- Не злоупотребляйте вложенностью. /users/123/orders/456 — это нормально. Но не делайте /users/123/orders/456/payments/789/... Ограничьте глубину 2-3 уровня.
- Пагинация обязательна для любых списков. Никогда не отдавайте все 10 000 записей сразу. limit + offset (самый простой) или cursor-based пагинация (лучше для больших данных).
- Позволяйте клиенту выбирать, какие поля ему нужны (sparse fields). Например, /users?fields=id,name,email — вернёт только указанные поля. Это уменьшает объём данных.
- Кешируйте ответы, где это безопасно. Заголовки Cache-Control (public, max-age=3600).
- Используйте асинхронные операции для «тяжёлых» задач. Клиент POST запрос -> API возвращает 202 Accepted и task_id -> Клиент периодически запрашивает статус задачи (GET /tasks/{task_id}).
Сравнение: REST vs GraphQL vs gRPC
| Критерий | REST | GraphQL | gRPC |
|---|---|---|---|
| Сложность реализации | Низкая—— | Средняя—— | Высокая—— |
| Гибкость (клиент выбирает поля) | Нет (фиксированные ответы) | Да (любые поля) | Ограниченно |
| Кеширование на уровне HTTP | Отлично | Сложно (по умолчанию не кешируется) | Н/Д |
| Производительность (бинарный протокол) | Средняя (JSON) | Средняя (JSON + усложнение) | Высокая (Protocol Buffers) |
Когда что выбирать:
- REST — 80% проектов. Клиент — сайт и мобильное приложение. Просто, понятно, кешируется.
- GraphQL — когда клиенту нужна максимальная гибкость (разные приложения с разными наборами полей), и вы готовы к сложности реализации.
- gRPC — для внутреннего обмена между микросервисами, где важна скорость и нужен бинарный протокол.
Чек-лист: хороший ли у вас API
- [ ] Соответствует принципам REST (ресурсы, HTTP-методы, статусы).
- [ ] Использует HTTPS.
- [ ] Есть версионирование (в URL или заголовке).
- [ ] Есть документация (Swagger, Postman).
- [ ] Есть пагинация (limit/offset или cursor).
- [ ] Есть понятные сообщения об ошибках (не просто 500).
- [ ] Есть rate limiting.
- [ ] Валидация входных данных на сервере.
- [ ] Есть возможность запрашивать только нужные поля (sparse fields).
- [ ] Для долгих операций используется асинхронный подход (task_id).
🔌 Проектирование и разработка API под ключ
Спроектируем API для вашего сайта и мобильных приложений. Сделаем документацию в Swagger, настроим rate limiting, поможем выбрать REST или GraphQL. API не будет «тормозить» и не «сломает» мобильные приложения при обновлении.
👉 Оставьте заявку на сайте edgesection.ru или напишите в Telegram. Укажите «API проект».
Разработка сложных веб-проектов и приложений для бизнеса.
Резюме: главное о проектировании API
- API — это публичный интерфейс вашего сервера. Как он спроектирован, настолько легко будет пилить фронтенд и приложения.
- Придерживайтесь RESTful принципов: ресурсы, HTTP-методы, статусы, человекопонятные URL.
- Обязательно версионируйте API с первого дня (/v1). Это спасёт вас от кошмара обратной совместимости.
- Документация — это не роскошь, а необходимость (Swagger, OpenAPI).
- Закладывайте пагинацию, rate limiting, асинхронные операции для тяжёлых задач.
- Для 90% проектов вполне достаточно REST. GraphQL сложнее, но гибче. gRPC — для микросервисов.
