REST API: что это, принципы и примеры запросов

• 25 мин чтения

REST API позволяет программам работать с ресурсами через общий интерфейс. Например, приложение создаёт задачу запросом POST /tasks, а читает её через GET /tasks/1. Сервер возвращает статус операции и, когда нужно, представление ресурса.

REST расшифровывается как Representational State Transfer, «передача состояния представления». Это архитектурный стиль: он задаёт ограничения взаимодействия компонентов. В повседневной разработке REST API часто называют ресурсный HTTP API. Именно такой интерфейс мы спроектируем для списка задач.

Статья рассчитана на разработчика, который уже встречал HTTP-запросы и JSON, но ещё не проектировал свой API. Вы сможете выбрать адреса и методы, описать ошибки, добавить пагинацию и защитить изменения от перезаписи. Примеры запросов и ответов можно читать без запуска. Для практики есть локальный сервер на Go; объяснение контракта подходит и для другого стека.

Быстрые переходы: методы, практикум, ошибки, пагинация, защита через ETag, самопроверка.

Первый REST API: создание, изменение и удаление задачи

Скачайте исходники примера. В архиве сервер на стандартной библиотеке Go, тесты и описание OpenAPI. Для запуска нужны Go, unzip и curl. Команды ниже рассчитаны на Bash с sed и tr. Для чтения ссылки следующей страницы понадобится Python 3.

unzip rest-api-example.zip
cd rest-api-example
go run .

Сервер слушает 127.0.0.1:8080. Данные находятся в памяти и исчезнут при остановке. Аутентификация, проверка владельца и TLS не реализованы. Это локальный учебный сервер.

Оставьте его работать. Все следующие команды выполняйте по порядку во втором терминале на одном свежем сервере. Если повторили создание или перезапустили сервер, начните сценарий заново. Переменные Bash сохраняйте в этом же терминале.

Создайте и прочитайте задачу

base=http://127.0.0.1:8080
created=$(curl -si "$base/tasks" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Изучить REST"}')
printf '%s\n' "$created"
location=$(printf '%s\n' "$created" | tr -d '\r' | sed -n 's/^[Ll]ocation: //p')
url="$base$location"

--data выбирает POST. На свежем сервере ответ содержит:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /tasks/1
{"id":1,"title":"Изучить REST","done":false}

201 сообщает о создании, Location указывает адрес задачи. Прочитайте её:

saved=$(curl -sS -D - "$url")
printf '%s\n' "$saved"
etag=$(printf '%s\n' "$saved" | tr -d '\r' | sed -n 's/^[Ee][Tt][Aa][Gg]: //p')

В ответе 200 JSON показывает состояние задачи, а заголовок ETag обозначает версию этого представления. Сохраним оба из одного ответа. Что произойдёт, если два редактора откроют эту копию и каждый сохранит свои правки?

Замените состояние через PUT

curl -i -X PUT "$url" \
  -H 'Content-Type: application/json' \
  -H "If-Match: $etag" \
  --data '{"title":"Проверить REST API","done":false}'

Ответ 200:

{"id":1,"title":"Проверить REST API","done":false}

PUT передаёт оба изменяемых поля. Отправка только title даст 422. Поле id принадлежит серверу, клиент его не задаёт. If-Match разрешает запись только для прочитанной версии; ниже разберём, от какой ошибки это защищает.

Измените одно поле через PATCH

Оба редактора открывают задачу после PUT. Для опыта достаточно одного GET: оба видят одинаковое тело и получают один ETag.

saved=$(curl -sS -D - "$url")
printf '%s\n' "$saved"
etag=$(printf '%s\n' "$saved" | tr -d '\r' | sed -n 's/^[Ee][Tt][Aa][Gg]: //p')

Первый редактор отмечает задачу выполненной:

curl -i -X PATCH "$url" \
  -H 'Content-Type: application/merge-patch+json' \
  -H "If-Match: $etag" \
  --data '{"done":true}'

Ответ 200; заголовок задачи сохранился:

{"id":1,"title":"Проверить REST API","done":true}

Теперь переменная etag содержит старый валидатор. Попробуйте записать старую полную копию, как это сделал бы второй редактор:

curl -i -X PUT "$url" \
  -H 'Content-Type: application/json' \
  -H "If-Match: $etag" \
  --data '{"title":"Другое название","done":false}'

Сервер ответит 412 Precondition Failed. На схеме "v1" и "v2" обозначают ETag до и после первой записи.

Редактор АСерверРедактор БGETdone=false · "v1"GETdone=false · "v1"PATCH done=true · If-Match: "v1"200 OKPUT с новым названием и done=false · If-Match: "v1"412 Precondition FailedGETdone=true · "v2"
Два редактора открыли одну версию задачи. После записи А сервер отклоняет старую копию Б.

Без проверки версии второй PUT вернул бы done:false. С условием If-Match: * запись тоже прошла бы: звёздочка проверяет только существование задачи. Если пропустить условие, сервер вернёт 428:

curl -i -X PATCH "$url" \
  -H 'Content-Type: application/merge-patch+json' \
  --data '{"done":false}'

Проверьте сохранённое представление и удалите задачу

Прочитайте актуальное тело и сохраните заголовки GET в переменной. curl -D - выводит заголовки вместе с телом:

saved=$(curl -sS -D - "$url")
printf '%s\n' "$saved"
etag=$(printf '%s\n' "$saved" | tr -d '\r' | sed -n 's/^[Ee][Tt][Aa][Gg]: //p')

Проверьте в ответе поле done: оно сохранило значение true, хотя второй редактор отправил false.

Если с тех пор задача не менялась, условное чтение не передаёт тело заново:

curl -i "$url" -H "If-None-Match: $etag"

Получите 304 без тела. В приложении это сигнал использовать сохранённое представление. Здесь оно осталось в saved; сам curl -i прикладной кеш не ведёт.

Удалите задачу с той же актуальной версией:

curl -i -X DELETE "$url" -H "If-Match: $etag"

Повторите запрос:

curl -i -X DELETE "$url" -H "If-Match: $etag"

Первый ответ 204 без тела, второй 404. Эффект удаления сохранился: ресурса нет. Поэтому различие ответов не нарушает идемпотентность DELETE.

API, HTTP, REST и RESTful: в чём разница

ПонятиеЧто означаетПример
APIИнтерфейс взаимодействия программФункции библиотеки, интерфейс ОС, сетевой сервис
HTTPПротокол запросов и ответовGET, заголовки, статусы
RESTАрхитектурный стиль распределённой системыРесурсы, единый интерфейс, независимые запросы
RESTful APIAPI, соблюдающий ограничения RESTВ строгом смысле включая переходы через элементы управления
JSONФормат представления данных{"id":1,"done":false}

REST не привязан к JSON. Представлением может быть HTML, изображение или другой формат. HTTP подходит для REST, но эти понятия не равнозначны. CRUD, то есть создание, чтение, изменение и удаление данных, описывает лишь часть возможных операций.

В работе Roy Fielding REST определён через архитектурные ограничения. Поэтому «сервер возвращает JSON» ещё недостаточно, чтобы назвать интерфейс RESTful.

Шесть принципов REST

Пять ограничений обязательны, шестое опционально:

ОграничениеСмыслПрактическое следствие
Клиент и серверИнтерфейс отделяет потребителя от реализацииМожно менять хранилище без изменения клиентского контракта
StatelessЗапрос содержит контекст, необходимый для его пониманияСерверу не нужно помнить предыдущий шаг диалога клиента
КешированиеОтвет определяет возможность повторного использованияКлиент и посредник понимают политику кеша
Единый интерфейсКомпоненты взаимодействуют по общим правиламРесурсы идентифицируются, сообщения описывают себя
СлоиКомпонент взаимодействует с соседним слоемМежду клиентом и приложением могут стоять шлюз и прокси
Код по требованиюСервер может расширять возможности клиента кодомНапример, браузер получает JavaScript; это необязательно

Stateless не запрещает базу данных. Задачи, пользователи и заказы остаются состоянием ресурсов. Ограничение касается контекста клиентского диалога: запрос «продолжи действие, которое я выбрал раньше» требует памяти о предыдущем шаге. Запрос «измени задачу 17» с нужными данными задаёт операцию самостоятельно.

Серверная сессия, от которой зависит понимание последующих запросов, расходится со строгим stateless. При этом наличие cookie само по себе ничего не доказывает: cookie может передавать данные для самостоятельной обработки запроса. JWT также не делает архитектуру REST автоматически.

Единый интерфейс и HATEOAS

У единого интерфейса четыре составляющие: идентификация ресурсов, работа через представления, самодостаточные сообщения и управление переходами через гипертекст, или hypermedia.

Последнюю часть называют HATEOAS. Клиент получает данные вместе с доступными действиями. Их смысл задают правила формата представления и отношений ссылок.

Например, в формате представления заказа можно определить действие pay с адресом, методом POST и схемой платёжных данных. В состоянии unpaid сервер передаёт это действие, а в cancelled убирает его. Клиент показывает оплату только при наличии действия и использует переданный адрес. Ему всё равно нужно заранее знать смысл pay и правила формата. Сервер проверяет допустимость оплаты заново: состояние могло измениться после чтения.

Это отдельный пример проектирования. Его цена: разработчик должен описать формат действий, а клиент научиться им пользоваться. Добавить поле links недостаточно. Нужно определить смысл отношений и способ выполнения перехода. Это различие автор REST подчёркивает в REST APIs must be hypertext-driven.

Наш пример возвращает ссылки страниц, но не реализует полный интерфейс с гипертекстовыми переходами. Точнее назвать его ресурсным HTTP API. Такой формат широко встречается под названием REST API; дальше будем проектировать именно его, сохраняя это различие.

Ограничения нужны для независимого развития компонентов. Самодостаточный запрос проще направить на другой экземпляр сервера, но контекст приходится передавать снова. Кеш сокращает обращения, но требует правил свежести. Единый интерфейс уменьшает число специальных соглашений, хотя для узкой задачи отдельная команда иногда проще.

Как устроены HTTP-запрос и ответ

Рассмотрим чтение списка:

GET /tasks?done=false&limit=2 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer <token>

В запросе есть метод, адрес, заголовки и, при необходимости, тело. В адресе /tasks обозначает коллекцию, а параметры после ? задают фильтр и размер страницы. Заголовок авторизации здесь иллюстрирует запрос к защищённому API: учебный сервер его не проверяет.

Ответ может выглядеть так:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
  "items": [{"id":1,"title":"Изучить REST","done":false}],
  "links": {"self":"/tasks?done=false&limit=2"}
}

Content-Type описывает формат отправленного тела. Accept сообщает предпочтения получателя. Если сервер не поддерживает запрошенное представление, он может вернуть 406 Not Acceptable или проигнорировать предпочтение. В нашем примере ответы всегда JSON, согласование форматов не реализовано.

Выше показана текстовая запись HTTP/1.1. В HTTP/2 и HTTP/3 сообщение передаётся иначе; ресурсы, методы и статусы сохраняют смысл.

Как проектировать ресурсы и URL

Начните с задач потребителя. Какие объекты он видит? Какие действия выполняет? Какие результаты должен получить?

Для списка задач достаточно двух адресов:

URLРесурс
/tasksКоллекция задач
/tasks/17Отдельная задача

Существительные во множественном числе, нижний регистр и одинаковый стиль URL удобны как соглашение команды. Сам REST не требует именно множественного числа. Важнее устойчивые идентификаторы и понятный контракт.

Не переносите структуру таблиц в API автоматически. Клиенту обычно не нужны внутренние поля deleted_at, служебные флаги и названия связующих таблиц. Модель хранения можно менять отдельно от публичного представления.

Вложенные ресурсы и бизнес-действия

Адрес /projects/8/tasks удобен, когда задачи рассматриваются в контексте проекта. Для самой задачи можно сохранить канонический адрес /tasks/17. Глубокая цепочка /companies/2/teams/4/projects/8/tasks/17 усложняет изменение принадлежности и проверку прав.

Отмену заказа можно представить созданием ресурса:

POST /orders/42/cancellations HTTP/1.1
Content-Type: application/json

{"reason":"Заказ оформлен дважды"}

Это отдельный пример проектирования, в сервере задач такого маршрута нет. Ресурс отмены полезен, если у действия есть причина, автор и собственный результат. Не нужно придумывать фиктивный объект только ради отсутствия глагола в URL. Для командного API можно сознательно выбрать RPC и описать его правила.

HTTP-методы: GET, POST, PUT, PATCH и DELETE

МетодТипичная задачаБезопасныйИдемпотентный по семантике метода
GETПолучить представлениеДаДа
HEADПолучить заголовки без тела ответаДаДа
POSTОбработать данные, часто создать ресурс в коллекцииНетНет
PUTСоздать или полностью заменить состояние по известному адресуНетДа
PATCHПрименить документ измененийНетНе гарантируется
DELETEУдалить связь адреса с текущим ресурсомНетДа
OPTIONSУзнать доступные возможностиДаДа

Свойства методов описаны в справочнике MDN. Конкретный API вправе разрешать только часть методов. Например, учебный сервер не создаёт задачу через PUT и не реализует OPTIONS.

Безопасный метод не запрашивает изменение состояния ресурса. Сервер всё равно может вести журнал или собирать статистику. Удаление через GET опасно: ссылку могут открыть робот, предварительная загрузка браузера или кеш.

Идемпотентный метод при повторах имеет тот же предполагаемый эффект, что и один запрос. Ответы могут различаться. Первый DELETE вернёт 204, следующий 404, но задача не появится снова. Это не означает, что повтор с любым телом и в любой момент безопасен для бизнес-процесса: условия, конкурентные изменения и внешние эффекты тоже входят в проектирование операции.

PUT и PATCH: полная замена и частичное изменение

В нашем контракте PUT требует оба изменяемых поля:

{"title":"Изучить REST","done":true}

Поле id назначает сервер. «Полная замена» относится к состоянию, которое разрешено задавать клиенту. Это не требование отправлять все поля внутренней модели.

Для PATCH нужно выбрать формат документа изменений. JSON Merge Patch использует Content-Type: application/merge-patch+json:

{"done":true}

Неуказанные поля сохраняются. null означает удаление поля, массив заменяется целиком. Поскольку у нашей задачи title и done обязательны, попытка удалить их получает 422. Формат определён в RFC 7396.

Другой формат, JSON Patch, задаёт операции вроде replace и add. У него другой тип содержимого, application/json-patch+json. Не смешивайте эти форматы с произвольным JSON-объектом.

PATCH не является идемпотентным по определению метода. Установка done=true может быть идемпотентной, а операция «увеличить счётчик на один» нет. Сервер должен применять документ изменений атомарно: частично выполненный PATCH не должен стать виден клиенту. Эти условия описывает RFC 5789.

Коды ответов: что должен понять клиент

Успешный транспортный обмен ещё не означает успешную операцию. Клиент сначала проверяет статус, затем разбирает тело по подходящей схеме.

Предположим, клиент отправляет PATCH с типом application/merge-patch+json. Что ему исправить после ошибки?

Тело запросаIf-MatchОтветДействие клиента
{"done":Актуальный400Закончить документ JSON
{"done":"да"}Актуальный422Передать логическое значение
{"done":true}Устаревший412Перечитать задачу и сверить изменения
Справочник статусов HTTP и действий клиента
КодКогда полезенЧто делает клиент
200 OKУспех с представлениемЧитает тело
201 CreatedРесурс созданСохраняет адрес из Location, если он передан
202 AcceptedРабота принята, завершение ещё не подтвержденоСледит за операцией по контракту
204 No ContentУспех без телаНе пытается разобрать JSON
304 Not ModifiedУсловный GET/HEAD, представление не изменилосьИспользует сохранённое тело
400 Bad RequestНекорректный запросИсправляет запрос
401 UnauthorizedНет подходящих учётных данныхПроверяет аутентификацию; сервер передаёт WWW-Authenticate
403 ForbiddenСервер отказывает в выполненииПроверяет права, не повторяет бесконечно
404 Not FoundРесурс не найден или его наличие скрытоОбрабатывает отсутствие
405 Method Not AllowedМетод не разрешён для ресурсаСверяется с Allow
409 ConflictКонфликт с текущим состояниемРазрешает бизнес-конфликт
412 Precondition FailedНе выполнено условие запросаПеречитывает ресурс перед изменением
413 Content Too LargeСлишком большое телоУменьшает объём
415 Unsupported Media TypeНеподдерживаемый формат телаИсправляет Content-Type или формат
422 Unprocessable ContentФормат понятен, данные нельзя обработатьИсправляет значения
428 Precondition RequiredСервер требует условный запросПередаёт нужный If-Match
429 Too Many RequestsПревышен лимитУчитывает Retry-After, если он есть
500 Internal Server ErrorНеожиданная ошибка сервераФиксирует идентификатор ошибки, проверяет политику повторов
503 Service UnavailableСервис временно недоступенУчитывает условия повторов и Retry-After

Базовая семантика определена в RFC 9110; 428 и 429 добавлены в RFC 6585. 204 и 304 не содержат тела ответа.

Разделение 400 и 422 уточните в контракте. В примере сломанный JSON и неизвестное поле дают 400; пустой заголовок задачи или done строкой вместо логического значения дают 422. Выбор должен быть предсказуемым во всех маршрутах.

Для долгой операции полезна пара 202 и адрес ресурса операции, например /operations/91. Он сообщает pending, succeeded или failed. Это отдельное соглашение API: один статус 202 не создаёт механизм отслеживания автоматически.

Ошибки и валидация: один формат для всех маршрутов

Клиенту трудно обрабатывать API, где один маршрут возвращает строку, другой HTML, третий {"success":false} со статусом 200.

Для ошибок можно использовать Problem Details из RFC 9457. В примере запрос с пустым title:

curl -i http://127.0.0.1:8080/tasks \
  -H 'Content-Type: application/json' \
  --data '{"title":""}'

получает 422 и Content-Type: application/problem+json:

{
  "type":"about:blank",
  "title":"Unprocessable Entity",
  "status":422,
  "detail":"Исправьте указанные поля",
  "errors":[{"pointer":"/title","code":"required"}]
}

type идентифицирует вид проблемы, title даёт краткое описание, detail поясняет конкретную ошибку. Вариант about:blank использует смысл HTTP-статуса. Для собственных типов ошибок задайте устойчивые URI с документацией. Поле status в теле не заменяет настоящий статус ответа.

errors здесь является расширением нашего контракта, а не обязательным полем Problem Details. pointer указывает поле по правилам JSON Pointer. Код required означает отсутствие обязательного значения, invalid_type неверный тип, too_long превышение длины. Форма может подсветить title по /title и вывести своё сообщение по коду required. Разбирать русскую фразу из detail для этого не нужно. Стек вызовов, SQL и секреты остаются в серверных журналах.

Что проверять на входе

В примере есть несколько независимых проверок:

В другом API политика неизвестных полей может отличаться. Зафиксируйте её явно. Для ответов полезна терпимость потребителя к новым полям: иначе сервер не сможет расширить представление без одновременного обновления всех клиентов.

Отдельные структуры запросов помогают не открыть изменение служебных полей через автоматическую привязку JSON к модели базы данных.

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

Маршрут коллекции не должен бесконтрольно возвращать все данные. Даже если задач пока десять, договоритесь о пределе страницы.

В примере доступны done, limit от 1 до 100 (по умолчанию 2) и курсор after. Порядок всегда по возрастанию ID. Начните с пустого учебного сервера (команда запуска приведена в практикуме). Создайте три задачи:

for title in 'Первая' 'Вторая' 'Третья'; do
  curl -i http://127.0.0.1:8080/tasks \
    -H 'Content-Type: application/json' \
    --data "{\"title\":\"$title\"}"
done

Получите первые две незавершённые задачи:

base=http://127.0.0.1:8080
page=$(curl -si "$base/tasks?done=false&limit=2")
printf '%s\n' "$page"

В items находятся «Первая» и «Вторая». Извлеките links.next из тела ответа и запросите следующую страницу:

next=$(printf '%s\n' "$page" | tr -d '\r' | sed '1,/^$/d' | python3 -c 'import json, sys; print(json.load(sys.stdin)["links"]["next"])')
curl -i "$base$next"

На второй странице останется «Третья». В links будет только адрес самой страницы.

Клиент следует ссылке, пока есть next. Не вычисляйте курсор самостоятельно. Пустая коллекция возвращает "items":[] со статусом 200, а не 404.

Offset или курсор

ПодходКогда удобенОграничение
offset=40&limit=20Нужны номера страниц и переход к известному смещениюВставки и удаления сдвигают результаты; большое смещение может дорого обходиться БД
Курсор после последнего ключаЛента, последовательный обход, большие коллекцииПроизвольный переход к странице обычно не предусмотрен

Для курсора нужен устойчивый однозначный порядок. Если сортируете по дате, добавьте ID как дополнительный ключ: (created_at, id). Разрешённые поля сортировки задавайте списком. Не подставляйте произвольную строку клиента в SQL.

Курсор примера содержит ID и фильтр в Base64url. Для клиента это непрозрачная строка: её устройство не входит в контракт. Кодирование не шифрует данные и не защищает от подмены. Проверка доступа к задачам всё равно нужна.

Курсор также не гарантирует снимок коллекции. Между страницами задачу могут удалить или изменить так, что она перестанет подходить фильтру. Если нужен точный экспорт на один момент времени, проектируйте отдельную гарантию снимка.

Учебный сервер копирует подходящие задачи и сортирует их в памяти. Для большой коллекции переносите ограничение выборки и порядок в запрос БД, создавайте подходящий индекс. Само наличие limit в URL не ограничивает работу хранилища.

Как ETag и If-Match защищают от потери изменений

Представьте двух клиентов. Оба прочитали одну задачу. Первый поменял заголовок. Второй отправил свою старую копию, изменив только done. Без проверки версии он может затереть новый заголовок.

ETag служит валидатором представления. Клиент получает его через GET, затем передаёт в If-Match. При несовпадении сервер отвечает 412. Для этой проверки требуется сильное сравнение: слабый валидатор с префиксом W/ не подходит. Подробности есть в документации If-Match.

PATCH одного поля уменьшает риск затереть другое поле. Если оба редактора меняют одно и то же поле, конфликт остаётся.

В практикуме оба клиента передают ETag прочитанной версии. Первая запись меняет версию; вторая получает 412, и данные остаются прежними. Клиент должен перечитать задачу и предложить пользователю совместить изменения. Автоматически брать свежий ETag и повторять старую полную копию нельзя: это обходит защиту.

Проверка версии должна быть атомарной с записью

Если проверить ETag, отпустить блокировку, а затем изменить объект, другой запрос успеет вклиниться между этими действиями. В примере проверку и запись защищает один mutex. Запись HTTP-ответа происходит после снятия блокировки.

Для БД такой же смысл имеет условное изменение по ID и версии с проверкой числа обновлённых строк. Если изменено ноль строк, отдельно выясняют отсутствие ресурса или конфликт версии. Блокировка одного Go-процесса не защищает несколько экземпляров сервиса.

Сильный ETag должен различать разные представления одного ресурса. В примере он содержит случайный идентификатор запуска, ID задачи и счётчик версии. После перезапуска ID могут повториться, но старый ETag не подойдёт к новой задаче. Без идентификатора запуска клиент мог бы получить 304 для другого тела или изменить новую задачу со старым If-Match.

Для постоянного сервиса версии должны учитывать также смену формата и зависимые данные. Можно сохранять версии либо вычислять валидатор из представления. Клиент хранит ETag как полученную строку вместе с кавычками и не вычисляет следующую версию.

If-Match: * проверяет наличие текущего ресурса, а не конкретную версию. Это не равно защите от перезаписи чужих изменений.

Ещё одна деталь: наш PUT нормализует title, убирая пробелы. Успешный PUT не возвращает валидатор преобразованного тела; новый ETag клиент получает отдельным GET. Это условие часто теряется в примерах с автоматической сериализацией.

Кеширование: ETag, If-None-Match и Cache-Control

Кеширование и защита записи используют один валидатор, но разные условия:

Заголовок запросаВопрос клиентаТипичный результат
If-None-Match при GETИзменилось ли сохранённое представление?304 или новое тело с 200
If-Match при измененииВсё ещё актуальна версия, которую я редактировал?Успех или 412

В практикуме GET сохранил JSON задачи и ETag. Следующий запрос с If-None-Match получил 304: клиент может использовать сохранённое тело. Если задачу изменили, сервер вернёт 200, новое тело и новый ETag. Один 304 без ранее сохранённого представления не даёт клиенту данных.

Заголовок Cache-Control определяет, как хранить и повторно использовать ответ:

В примере GET задачи возвращает private, no-cache; остальные ответы получают no-store. Это учебная политика, а не универсальная настройка для всех API. Для персональных данных отдельно учитывайте авторизацию, общий кеш и ключ кеширования. Правила определены в RFC 9111.

Если представление зависит от заголовков запроса, корректный Vary помогает кешу различать варианты. Сам Vary не делает общий кеш безопасным для любых секретных данных.

Повторы запросов и Idempotency-Key

Клиент отправил POST и дождался таймаута. Можно ли оформить заказ повторно? Ответ зависит от того, как сервер обрабатывает повторы.

КлиентСервис заказовPOST /orders · ключ KСохраняет заказ № 42 и результат для KОтправляет 201. Ответ теряется в сетиТаймаут. Номер заказа неизвестенPOST /orders · то же тело и ключ K201 Created · Location: /orders/42
Ответ на первый POST потерялся. В этом примере сервис узнаёт повтор по ключу и возвращает номер уже созданного заказа.

Без поддержки ключей второй POST мог бы создать ещё один заказ. Новый ключ при каждой попытке тоже допускает дубль.

Для операций, где дубль недопустим, API может поддерживать Idempotency-Key. Клиент выбирает ключ одной логической операции и сохраняет его при повторах. Сам по себе произвольный заголовок ничего не гарантирует: сервер должен реализовать и описать его обработку.

В статье Stripe об идемпотентности разобраны неоднозначные сетевые сбои и повторы с ключом. Для собственного сервиса нужно решить, как хранить результат и как координировать одновременные запросы.

Возможная схема для создания заказа:

  1. Область ключа включает пользователя и операцию. Чужой запрос не должен получить сохранённый ответ.
  2. Сервер связывает ключ с отпечатком значимых данных. Тот же ключ с другим содержимым отклоняет по контракту.
  3. Регистрация ключа, бизнес-изменение и фиксация результата согласованы атомарно. Одной записи в локальную map недостаточно при нескольких экземплярах сервиса.
  4. Для незавершённой операции определено поведение параллельного повтора.
  5. Срок хранения опубликован. После его истечения прежняя защита от дубля может перестать действовать.

Это схема проектирования, а не готовая реализация из архива. Учебный POST не поддерживает ключи идемпотентности.

Какие ошибки повторять

Повторять каждый 4xx бессмысленно. Неверный JSON не исправится от ожидания. Для 429, временной недоступности или сетевого сбоя учитывайте семантику операции, общий срок выполнения и контракт API.

Практический алгоритм: ограничить число попыток, увеличивать задержку, добавлять случайный разброс и учитывать Retry-After, если он передан. Проверяйте, что тело запроса можно отправить повторно. Условный запрос со старым ETag после потерянного ответа может получить 412: сначала выясните текущее состояние.

Для клиента на Go задайте таймауты HTTP-запросов. Таймаут и отмена ожидания сами по себе не откатывают уже выполненное изменение на сервере.

Безопасность REST API: права, токены и CORS

REST не задаёт способ аутентификации. Bearer-токен, cookie и OAuth решают отдельные задачи. JWT представляет формат токена; наличие JWT не заменяет проверку подписи, срока, назначения и прав.

Разделяйте два вопроса:

После проверки токена запрос /tasks/17 всё ещё может обращаться к чужим данным. Проверка прав нужна для каждого объекта и действия, включая выдачу списков. Подмена числового ID на UUID эту задачу не решает. Такой класс ошибок описан в OWASP: Broken Object Level Authorization.

Перед запуском защищённого API проверьте также HTTPS, лимиты размера и частоты запросов, разрешённые поля изменения, время выполнения и объём ответа. Не передавайте токены в URL: адреса часто попадают в историю и журналы. Не записывайте секреты и полные персональные данные в диагностические сообщения.

Почему curl работает, а браузер пишет про CORS

CORS управляет доступом браузерного JavaScript к ответам другого источника. Это не аутентификация API. Серверный клиент или curl не обязаны соблюдать браузерные ограничения CORS.

Для некоторых запросов браузер сначала отправляет OPTIONS с проверкой разрешений. Сервер должен согласовать допустимые источники, методы и заголовки. Если браузерному коду нужен ETag ответа другого источника, настройте и Access-Control-Expose-Headers: ETag. Для запросов с учётными данными есть дополнительные ограничения; настройки описаны в руководстве MDN по CORS.

При аутентификации через cookie отдельно учитывайте CSRF: разрешение читать ответ и возможность отправить запрос не совпадают. Access-Control-Allow-Origin: * не является защитой от чужого доступа к API.

OpenAPI и Swagger: как описать контракт

OpenAPI описывает операции HTTP API в машиночитаемом виде. По документу можно строить справку, генерировать клиентский код и проверять сообщения. Swagger UI показывает такой документ в браузере. Ни инструмент, ни наличие спецификации сами по себе не делают API RESTful.

В архиве есть полный openapi.json учебного интерфейса в формате OpenAPI 3.1.1. Ниже небольшой фрагмент того же контракта в YAML, только для тела POST:

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required: [title]
        additionalProperties: false
        properties:
          title:
            type: string
            description: "После удаления пробелов по краям: от 1 до 120 символов"
          done:
            type: boolean

Схема ограничивает форму данных. Нормализацию title, атомарность записи и гарантию повторов нужно описать дополнительно и проверить тестами. Не считайте сгенерированную страницу доказательством, что реализация соблюдает контракт. Формальные правила документа есть в OpenAPI Specification.

Какие тесты полезнее проверки «вернулся 200»

Тестируйте наблюдаемое поведение клиента:

СценарийОжидаемое свойство
Создание задачи201, корректное тело, Location
Неподдерживаемый формат415, единая схема ошибки
Пустой title422, задача не создана
Две одновременные записи с одним ETagОдна проходит, другая получает 412
Условный GET актуальной версии304, тела нет
DELETE, затем повтор DELETEСначала 204, затем отсутствие ресурса
Последняя страница спискаНет links.next, порядок не меняется
Чтение чужой задачи в защищённом APIДанные не выдаются, права проверены

Последняя строка относится к вашему защищённому сервису, а не к учебному серверу без пользователей. В архиве main_test.go проверяет остальные группы сценариев, включая конкурентную запись. verify.py дополнительно проверяет реальные HTTP-ответы по схемам OpenAPI и выполняет команды curl из этой статьи.

Из каталога примера можно запустить (для -race нужен C-компилятор):

go test -race -count=1 ./...
go vet ./...

Для verify.py нужны Python и пакет jsonschema; зависимости и воспроизводимая проверка через Nix описаны в README. Проверка схем ответов не заменяет полную проверку всех правил документа OpenAPI.

Как устроен пример на Go

HTTP-обработчик change проверяет тип и размер тела, разбирает JSON, затем вызывает mutate. Эта функция работает с копией задачи под блокировкой. До успешной проверки If-Match изменения не попадают в хранилище.

func (a *api) mutate(id int64, method string, fields map[string]json.RawMessage, condition string, present bool) (task, int, string, []fieldError) {
	a.mu.Lock()
	defer a.mu.Unlock()
	t, exists := a.tasks[id]
	if !exists {
		return task{}, 404, "Задача не найдена", nil
	}
	if method != http.MethodDelete {
		updated, issues := apply(t.task, fields, method == http.MethodPut, method == http.MethodPut)
		if len(issues) != 0 {
			return task{}, 422, "Исправьте указанные поля", issues
		}
		t.task = updated
	}
	if !present {
		return task{}, 428, "Сначала получите ETag и передайте его в If-Match", nil
	}
	match, err := matches(condition, t.etag(), false)
	if err != nil {
		return task{}, 400, "Некорректный If-Match", nil
	}
	if !match {
		return task{}, 412, "Версия задачи изменилась; получите её заново", nil
	}
	if method == http.MethodDelete {
		delete(a.tasks, id)
		return task{}, 204, "", nil
	}
	t.version++
	a.tasks[id] = t
	return t.task, 200, "", nil
}

apply возвращает изменённую копию и ошибки полей. Отсутствующий done сохраняет значение при PATCH; done:null даёт ошибку required. Входные поля хранятся как json.RawMessage, поэтому отсутствие, null и логическое значение различимы. Подробнее о таком разборе: JSON в Go.

Пока функция держит блокировку, она проверяет версию и сохраняет изменение. При выходе defer освобождает mutex. Только затем обработчик пишет HTTP-ответ. Медленный получатель ответа не удерживает блокировку хранилища. В базе данных эту гарантию должна обеспечивать условная запись по версии либо транзакция; mutex одного процесса не координирует несколько серверов.

Полный код чтения тела через http.MaxBytesReader, маршруты и ответы находятся в архиве. HEAD, 204 и 304 обходятся без тела. Для 405 сервер передаёт Allow. Таймауты ограничивают чтение и запись соединения; обращения к внешним зависимостям потребовали бы собственных сроков выполнения.

Совместимость и версии API

Изменение реализации не должно неожиданно ломать клиента. До выпуска обновления проверьте, какие предположения уже стали частью контракта.

ИзменениеЧто проверить
Добавлено поле ответаПотребители допускают неизвестные поля
Добавлено значение перечисленияКлиент умеет обрабатывать неизвестное значение
Поле стало обязательным в запросеСтарые клиенты продолжают работать или получили новую версию
Изменились сортировка и страница по умолчаниюОбход коллекции и сохранённые курсоры остаются корректными
Изменился смысл ошибкиКлиентская логика не опирается на прежнее поведение
Число заменено строкойЭто изменение типа, а не косметическая правка

Например, сервер добавил created_at в ответ задачи. Старая схема Task из архива допускает дополнительные поля, поэтому такой ответ проходит проверку. Для входных данных схема строже: клиентские поля перечислены явно.

Добавление поля часто совместимо, но не автоматически: строгий декодер может отклонить ответ. Заранее определите правила расширения и проверьте реальные клиентские реализации.

Версию можно указывать в URL, например /v1/tasks, либо согласовывать через заголовки и формат представления. Это выбор контракта, не обязательное требование REST. У каждого подхода есть цена для маршрутизации, кеширования и поддержки клиентов.

Если выпускаете несовместимую версию, назначьте срок поддержки старой, дайте описание перехода и способ проверить клиентов до отключения. Один новый префикс /v2 не решает миграцию.

Проверка перед выпуском: пройдите путь клиента

Проверьте контракт на небольшом сценарии, похожем на реальное использование:

  1. Клиент создаёт объект и получает его адрес. Какие поля обязательны? Как он узнаёт об ошибке?
  2. Клиент читает объект и страницу списка. Есть ли предел размера, устойчивый порядок и следующая ссылка?
  3. Два клиента меняют одну версию. Может ли второй затереть результат первого?
  4. Сервер выполнил операцию, но ответ потерялся. Что произойдёт при повторе?
  5. Пользователь подставил ID чужого объекта. На каком шаге проверяются права?
  6. Новая версия сервера добавила поле или значение перечисления. Как поведёт себя старый клиент?
  7. Зависимость зависла. Ограничены ли ожидание, число повторов и расход ресурсов?

В журнале связывайте запрос и ошибки зависимостей одним идентификатором. Измеряйте частоту ошибок и время ответа, включая медленные запросы со статусом 200. По идентификатору должно быть возможно найти сбой без записи токенов и полных персональных данных.

Практика: объясните решения своего API

Запустите сервер заново и проверьте себя:

  1. Создайте задачу и отправьте PUT только с title и актуальным ETag. Ожидайте 422 и errors с указателем /done: PUT требует оба изменяемых поля.
  2. Отправьте PATCH с {"done":null}. Ожидайте 422; прочитайте задачу и убедитесь, что она не изменилась. Отсутствие поля и его удаление имеют разный смысл.
  3. Прочитайте один ETag в двух терминалах и измените задачу из обоих. Одна запись пройдёт, другая получит 412. Объясните, почему нельзя просто заменить ETag и повторить старое тело.
  4. Создайте три задачи и пройдите список по links.next. На последней странице нет следующей ссылки. Объясните, почему это ещё не гарантирует снимок данных на один момент времени. Для этого задания также начните с пустого сервера.
  5. Сохраните ETag, перезапустите сервер и создайте другую задачу с тем же ID. Условный GET со старым ETag должен вернуть 200, а изменение со старым If-Match получить 412.

Для самопроверки спроектируйте API заметок: адреса коллекции и заметки, обязательные поля, изменение текста, ошибки и доступ владельца. Объясните поведение при двух редакторах и потерянном ответе на создание. Если затрудняетесь обосновать эти решения перед Go-собеседованием, их можно разобрать на консультации по подготовке.

Частые вопросы о REST API

Можно ли передавать тело в GET-запросе?
Для содержимого GET нет общей семантики, на которую можно надёжно рассчитывать между произвольными клиентами и посредниками. Не проектируйте общедоступный поиск с обязательным телом GET. Используйте параметры запроса, а для сложного запроса при необходимости отдельную POST-операцию с описанной семантикой. Это не делает POST безопасным или идемпотентным по определению метода.
Всегда ли POST создаёт ресурс, а PUT только обновляет?
Нет. POST просит ресурс обработать переданные данные; создание в коллекции лишь распространённый случай. PUT задаёт состояние по известному адресу и может создавать ресурс, если это разрешает сервер. Наш учебный API разрешает PUT только для существующих задач. Эти условия нужно читать в контракте.
Нужен ли JWT для REST API?
Нет. REST не требует конкретного механизма аутентификации или формата токена. Для закрытого API нужно выбрать механизм под свою среду, а затем проверять права на каждый объект и действие. Один JWT не решает авторизацию и не доказывает stateless.
Почему If-Match и Idempotency-Key не заменяют друг друга?
If-Match проверяет условие о текущем представлении и помогает предотвратить потерянное обновление. Ключ идемпотентности связывает повтор с одной логической операцией, например созданием заказа после сетевого сбоя. У них разные задачи и разные правила серверной реализации.

Что читать дальше

Точную семантику HTTP проверяйте по RFC, указанным в разделах статьи. Сервер и задания созданы для этого материала; это не примеры из перечисленных книг.


Об авторе: Александр Бруяко — руководитель разработки с опытом в backend, инфраструктуре и управлении командами.


Теги: