REST API

01Ресурсы и URL

REST (Representational State Transfer) моделирует предметную область как ресурсы — существительные вроде products, orders и customers. У каждого ресурса есть URL, а метод говорит, что с ним сделать. Используйте существительные во множественном числе и ID: /orders, /orders/1001, /orders/1001/items. Избегайте глаголов в путях вроде /getOrders или /createOrder — это уже говорит метод. Держите вложенность неглубокой (обычно хватает одного уровня). Действия, которые плохо ложатся на CRUD, моделируйте как подресурсы или изменения состояния: POST /orders/1001/cancellation или PATCH /orders/1001 с полем status. Используйте единообразное именование (camelCase или snake_case — выберите одно), даты ISO 8601 в UTC и ID, которые не выдают объёмы бизнеса, когда это важно. Аналогия: ресурсы — комнаты в здании, URL — их адреса, а методы — то, что вы в комнате делаете.

1GET    /v1/orders?status=pending&page=2   # list
2POST   /v1/orders                         # create
3GET    /v1/orders/1001                    # read one
4PATCH  /v1/orders/1001                    # partial update
5DELETE /v1/orders/1001                    # delete
6GET    /v1/customers/77/orders            # related collection
7POST   /v1/orders/1001/refunds            # action as sub-resource

02Методы, статус-коды и формат ошибок

Сопоставляйте операции с методами, а результаты — со статус-кодами. Создание возвращает 201 Created с заголовком Location и новым ресурсом. Успех без содержимого — 204. Ошибки валидации — 422 (или 400 для некорректного JSON) с деталями по полям. Не аутентифицирован — 401, нет прав — 403, не найдено — 404, конфликт версии или состояния — 409, слишком много запросов — 429, баги сервера — 500. Выберите один формат ошибок и используйте его везде. RFC 9457 Problem Details (application/problem+json) — хороший стандарт: type, title, status, detail плюс ваши собственные поля, например ошибки по полям и request ID для поддержки. Никогда не отдавайте в продакшен-ошибках стектрейсы или SQL.

1HTTP/1.1 422 Unprocessable Content
2Content-Type: application/problem+json
3 
4{
5  "type": "https://api.example.com/problems/validation",
6  "title": "The request has invalid fields.",
7  "status": 422,
8  "errors": { "quantity": ["Must be at least 1."] },
9  "requestId": "req_7f3a9c"
10}

03Пагинация, фильтрация, сортировка

Никогда не возвращайте неограниченные списки. Offset-пагинация (?page=3&per_page=20) проста и позволяет перейти на любую страницу, но на больших таблицах становится медленной и может пропускать или повторять элементы, когда данные меняются. Курсорная пагинация (?cursor=eyJpZCI6MTAwMH0&limit=20) использует непрозрачный указатель, например последний увиденный ID и created_at; она быстрая и стабильная для лент, бесконечной прокрутки и синхронизаций, но не позволяет прыгнуть на 50-ю страницу. Возвращайте метаданные или ссылки, чтобы клиенты не собирали URL сами. Для фильтрации используйте понятные query-параметры (?status=paid&created_from=2026-01-01), для сортировки — ?sort=-created_at,total, для поиска — ?q=. Ограничивайте максимальный размер страницы и разрешайте фильтрацию и сортировку только по индексированным полям.

1GET /v1/orders?status=paid&sort=-created_at&limit=20&cursor=eyJpZCI6MTAyMH0
2 
3{
4  "data": [ { "id": 1019, "total": 12500, "status": "paid" } ],
5  "meta": { "limit": 20, "hasMore": true },
6  "links": { "next": "/v1/orders?status=paid&sort=-created_at&limit=20&cursor=eyJpZCI6MTAwMH0" }
7}

04Версионирование и безопасное развитие

Клиенты, особенно мобильные приложения, которые пользователи не обновляют, зависят от вашего API годами. Добавляющие изменения безопасны: новые эндпоинты, новые необязательные поля, новые значения enum, если клиентам сказали терпимо относиться к неизвестным. Ломающие изменения — удаление или переименование полей, смена типов или смысла, превращение необязательного входного параметра в обязательный. Для ломающих изменений вводите новую версию. Версионирование в URL (/v1, /v2) самое заметное, и его проще всего маршрутизировать, кэшировать и отлаживать; версионирование через заголовок или media type сохраняет URL чистыми, но его сложнее тестировать. Некоторые API используют версии-даты в заголовке. Что бы вы ни выбрали, объявляйте об устаревании с датами, отправляйте заголовки Deprecation и Sunset и отслеживайте, какие клиенты всё ещё вызывают старые версии, прежде чем их отключать. Дополните это механизмом принудительного обновления в мобильных приложениях.

05Аутентификация, идемпотентность и rate limit'ы

Выбирайте способ аутентификации по типу клиента. Браузерные приложения на том же сайте: защищённые HttpOnly-cookie сессии плюс защита от CSRF. Мобильные и SPA-клиенты: короткоживущие access-токены (часто JWT) с refresh-токенами, через потоки OAuth 2 с PKCE для входа через сторонние сервисы. Партнёры «сервер–сервер»: API-ключи с ограниченными правами или OAuth client credentials, передаваемые в заголовках, никогда в URL. Сеть сбоит, поэтому делайте запись безопасной для повторов: клиенты отправляют заголовок Idempotency-Key с уникальным значением; сервер сохраняет ключ вместе с результатом и при повторе ключа возвращает тот же ответ, вместо того чтобы списать деньги или создать заказ дважды. Защищайте API rate limit'ами по ключу, пользователю или IP, отвечайте 429 с Retry-After и показывайте лимиты в заголовках, чтобы клиенты могли сбавить темп.

1POST /v1/payments HTTP/1.1
2Authorization: Bearer <access_token>
3Idempotency-Key: 6f1c2d4e-8a7b-4c3d-9e2f-1a2b3c4d5e6f
4Content-Type: application/json
5 
6{"orderId": 1001, "amount": 12500, "currency": "AMD"}
7 
8HTTP/1.1 429 Too Many Requests
9Retry-After: 30
10RateLimit-Policy: "default";q=100;w=60

06Документация в OpenAPI

OpenAPI (актуальная версия 3.1 согласована с JSON Schema) описывает ваши эндпоинты, параметры, тела запросов и ответов, ошибки и аутентификацию в файле YAML или JSON. Из этого единого источника вы получаете интерактивную документацию (Swagger UI, Redoc, Scalar), сгенерированные типизированные клиенты для TypeScript, Kotlin или Swift, mock-серверы и контрактные тесты. Генерируйте её из аннотаций или декораторов в коде (в NestJS есть встроенная поддержка, для Laravel — пакеты вроде Scramble), чтобы она никогда не расходилась с реальностью. Добавляйте примеры для каждого запроса и ошибки, описывайте пагинацию и rate limit'ы, публикуйте changelog. Хорошая документация — это фича: она сокращает время интеграции с недель до дней.

1paths:
2  /v1/orders/{id}:
3    get:
4      summary: Get one order
5      parameters:
6        - { name: id, in: path, required: true, schema: { type: integer } }
7      responses:
8        "200":
9          description: The order
10          content:
11            application/json:
12              schema: { $ref: "#/components/schemas/Order" }
13        "404": { $ref: "#/components/responses/NotFound" }

07REST, GraphQL, gRPC, WebSockets и вебхуки

Они решают разные задачи и часто живут бок о бок. REST — вариант по умолчанию для публичных и мобильных API: простой, кэшируемый, понятный любому инструменту. GraphQL позволяет клиентам запрашивать ровно те поля, которые нужны, с одного эндпоинта; это помогает, когда множество разных экранов собирают данные из многих источников, но цена — сложное кэширование, авторизация на уровне полей и лимиты стоимости запросов. gRPC использует Protocol Buffers поверх HTTP/2 со сгенерированными клиентами и стримингом; отлично подходит для быстрых типизированных вызовов между сервисами, неудобен в браузерах. WebSockets держат открытым двустороннее соединение для чатов, статуса заказа в реальном времени и дашбордов. Вебхуки — это «обратные API»: ваш сервер вызывает URL партнёра, когда что-то происходит, например платёж прошёл; подписывайте их HMAC, повторяйте с backoff и делайте получателей идемпотентными.

• Публичный, партнёрский или мобильный API: REST + OpenAPI.
• Много клиентов с очень разными потребностями в данных: рассмотрите GraphQL.
• Внутренние высоконагруженные сервисы: gRPC.
• Обновления пользователям в реальном времени: WebSockets или SSE. События для других систем: вебхуки.

08Авторизация — риск номер один для API

OWASP API Security Top 10 (2023) ставит на первое место Broken Object Level Authorization: API проверяет, что пользователь залогинен, но не проверяет, что заказ, счёт или файл, который он запрашивает, принадлежит ему, поэтому замена /orders/1001 на /orders/1002 раскрывает чужие данные. Сразу за ним идут broken function-level authorization (обычный пользователь вызывает админский эндпоинт) и broken object property level authorization (mass assignment, когда клиент выставляет role или price в теле PATCH). Надёжный паттерн — ограничивать каждый запрос вызывающим, а не проверять постфактум: загружайте данные через связь с пользователем или tenant, чтобы чужой ID просто ничего не находил и возвращал 404. Задавайте whitelist записываемых полей для каждого эндпоинта и используйте policy или guard, которые срабатывают на каждом маршруте. Случайные ID или ID с префиксом усложняют угадывание, но никогда не заменяют авторизацию.

1// Laravel: scope by owner, then authorize with a policy
2public function show(Request $request, int $id)
3{
4    $order = $request->user()->orders()->findOrFail($id); // 404 for others
5    $this->authorize('view', $order);
6    return new OrderResource($order);
7}
8 
9// Only allow known fields to be written
10$data = $request->validate([
11    'note'     => ['nullable', 'string', 'max:500'],
12    'quantity' => ['required', 'integer', 'min:1'],
13]);

09Долгие операции и надёжные события

Некоторые запросы не успевают завершиться за обычный таймаут: экспорты, импорты, обработка видео, массовые обновления. Вместо того чтобы держать соединение открытым, примите работу и верните 202 Accepted с заголовком Location, указывающим на ресурс статуса, например /v1/jobs/77. Клиент опрашивает этот ресурс или подписывается на вебхук и в конце переходит по ссылке на результат. Смежная проблема — надёжная публикация событий. Если код сохраняет заказ, а затем отправляет вебхук, падение между этими шагами теряет событие; если сначала отправить, а потом не сохранить, получится событие-призрак. Это решает паттерн transactional outbox: записывайте заказ и строку outbox в одной транзакции базы, а воркер доставляет строки outbox с повторами. Потребители всё равно должны дедуплицировать по ID события, потому что доставка — at least once.

1POST /v1/exports HTTP/1.1
2Content-Type: application/json
3 
4{"type": "orders", "from": "2026-10-01", "to": "2026-10-31"}
5 
6HTTP/1.1 202 Accepted
7Location: /v1/jobs/77
8 
9GET /v1/jobs/77  ->  {"status": "running", "progress": 40}
10GET /v1/jobs/77  ->  {"status": "done", "resultUrl": "/v1/exports/77/file"}

10Алгоритмы rate limiting

Fixed window считает запросы за календарную минуту; это просто, но на границе допускает двойные всплески (100 в 12:00:59 и 100 в 12:01:00). Sliding window учитывает с весом счётчик предыдущего окна, чтобы это сгладить. Token bucket даёт каждому клиенту «ведро», которое пополняется с постоянной скоростью до максимума, поэтому короткие всплески разрешены, а долгосрочная скорость остаётся фиксированной; это соответствует поведению реальных клиентов. Храните счётчики в Redis с атомарными операциями, чтобы их разделяли все серверы приложения. Ключи выбирайте аккуратно: по API-ключу для партнёров, по пользователю для залогиненного трафика, по IP — только в крайнем случае, ведь за NAT или мобильным оператором один IP могут делить многие пользователи. Возвращайте 429 с Retry-After и задавайте отдельные, более строгие лимиты для дорогих или чувствительных эндпоинтов вроде поиска, логина и экспортов.

1// Laravel: named limiters, applied with ->middleware('throttle:api')
2RateLimiter::for('api', function (Request $request) {
3    return $request->user()
4        ? Limit::perMinute(120)->by('user:'.$request->user()->id)
5        : Limit::perMinute(30)->by('ip:'.$request->ip());
6});
7 
8RateLimiter::for('login', fn (Request $request) =>
9    Limit::perMinute(5)->by($request->input('email').'|'.$request->ip())
10);

11Производительность: форма payload, N+1 и кэширование

Большинство медленных API медленны в базе данных. Эндпоинт списка, который загружает 50 заказов, а затем для каждого запрашивает клиента, делает 51 запрос: это проблема N+1. Используйте eager loading для связей, выбирайте только нужные колонки и добавляйте индексы под фильтры и сортировку; в разработке логируйте число запросов на каждый HTTP-запрос. Формируйте payload под клиента: sparse fieldsets (?fields=id,total,status) или параметры include (?include=customer) позволяют одному эндпоинту обслуживать и компактный список, и детальный просмотр. Сжимайте JSON через gzip или Brotli. Для ресурсов, которые часто читают, отправляйте ETag или Last-Modified, чтобы клиенты получали ответы 304, и кэшируйте вычисленные ответы в Redis с явной инвалидацией при записи. Публичные неперсональные эндпоинты, например каталог товаров, можно кэшировать в CDN через s-maxage. Измеряйте p95 latency по каждому эндпоинту, а не средние значения.