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 до и после первой записи.
Без проверки версии второй 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 API | API, соблюдающий ограничения 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 и секреты остаются в серверных журналах.
Что проверять на входе
В примере есть несколько независимых проверок:
- Тело не больше 16 КиБ, иначе
413. Лимит проверяется при чтении, а не только поContent-Length. - Формат соответствует операции: для POST и PUT нужен
application/json, для PATCH свой формат изменений. - Тело содержит один документ JSON в UTF-8. Два объекта подряд не принимаются.
titleпосле удаления пробелов по краям содержит от 1 до 120 кодовых точек Unicode.doneимеет логический тип.- Неизвестные поля запроса отклоняются. Клиент не может назначить себе
id.
В другом 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 определяет, как хранить и повторно использовать ответ:
max-age=60: ответ может оставаться свежим 60 секунд с учётом правил HTTP-кеша.no-cache: хранить можно, но перед повторным использованием нужна проверка у сервера.no-store: кеш не должен сохранять этот обмен.private: ответ предназначен для частного кеша, не для общего кеша между пользователями.
В примере GET задачи возвращает private, no-cache; остальные ответы получают no-store. Это учебная политика, а не универсальная настройка для всех API. Для персональных данных отдельно учитывайте авторизацию, общий кеш и ключ кеширования. Правила определены в RFC 9111.
Если представление зависит от заголовков запроса, корректный Vary помогает кешу различать варианты. Сам Vary не делает общий кеш безопасным для любых секретных данных.
Повторы запросов и Idempotency-Key
Клиент отправил POST и дождался таймаута. Можно ли оформить заказ повторно? Ответ зависит от того, как сервер обрабатывает повторы.
Без поддержки ключей второй POST мог бы создать ещё один заказ. Новый ключ при каждой попытке тоже допускает дубль.
Для операций, где дубль недопустим, API может поддерживать Idempotency-Key. Клиент выбирает ключ одной логической операции и сохраняет его при повторах. Сам по себе произвольный заголовок ничего не гарантирует: сервер должен реализовать и описать его обработку.
В статье Stripe об идемпотентности разобраны неоднозначные сетевые сбои и повторы с ключом. Для собственного сервиса нужно решить, как хранить результат и как координировать одновременные запросы.
Возможная схема для создания заказа:
- Область ключа включает пользователя и операцию. Чужой запрос не должен получить сохранённый ответ.
- Сервер связывает ключ с отпечатком значимых данных. Тот же ключ с другим содержимым отклоняет по контракту.
- Регистрация ключа, бизнес-изменение и фиксация результата согласованы атомарно. Одной записи в локальную map недостаточно при нескольких экземплярах сервиса.
- Для незавершённой операции определено поведение параллельного повтора.
- Срок хранения опубликован. После его истечения прежняя защита от дубля может перестать действовать.
Это схема проектирования, а не готовая реализация из архива. Учебный 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, единая схема ошибки |
Пустой title | 422, задача не создана |
| Две одновременные записи с одним 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 не решает миграцию.
Проверка перед выпуском: пройдите путь клиента
Проверьте контракт на небольшом сценарии, похожем на реальное использование:
- Клиент создаёт объект и получает его адрес. Какие поля обязательны? Как он узнаёт об ошибке?
- Клиент читает объект и страницу списка. Есть ли предел размера, устойчивый порядок и следующая ссылка?
- Два клиента меняют одну версию. Может ли второй затереть результат первого?
- Сервер выполнил операцию, но ответ потерялся. Что произойдёт при повторе?
- Пользователь подставил ID чужого объекта. На каком шаге проверяются права?
- Новая версия сервера добавила поле или значение перечисления. Как поведёт себя старый клиент?
- Зависимость зависла. Ограничены ли ожидание, число повторов и расход ресурсов?
В журнале связывайте запрос и ошибки зависимостей одним идентификатором. Измеряйте частоту ошибок и время ответа, включая медленные запросы со статусом 200. По идентификатору должно быть возможно найти сбой без записи токенов и полных персональных данных.
Практика: объясните решения своего API
Запустите сервер заново и проверьте себя:
- Создайте задачу и отправьте PUT только с
titleи актуальным ETag. Ожидайте422иerrorsс указателем/done: PUT требует оба изменяемых поля. - Отправьте PATCH с
{"done":null}. Ожидайте422; прочитайте задачу и убедитесь, что она не изменилась. Отсутствие поля и его удаление имеют разный смысл. - Прочитайте один ETag в двух терминалах и измените задачу из обоих. Одна запись пройдёт, другая получит
412. Объясните, почему нельзя просто заменить ETag и повторить старое тело. - Создайте три задачи и пройдите список по
links.next. На последней странице нет следующей ссылки. Объясните, почему это ещё не гарантирует снимок данных на один момент времени. Для этого задания также начните с пустого сервера. - Сохраните ETag, перезапустите сервер и создайте другую задачу с тем же ID. Условный GET со старым ETag должен вернуть
200, а изменение со старымIf-Matchполучить412.
Для самопроверки спроектируйте API заметок: адреса коллекции и заметки, обязательные поля, изменение текста, ошибки и доступ владельца. Объясните поведение при двух редакторах и потерянном ответе на создание. Если затрудняетесь обосновать эти решения перед Go-собеседованием, их можно разобрать на консультации по подготовке.
Частые вопросы о REST API
Можно ли передавать тело в GET-запросе?
Всегда ли POST создаёт ресурс, а PUT только обновляет?
Нужен ли JWT для REST API?
Почему If-Match и Idempotency-Key не заменяют друг друга?
Что читать дальше
- Тестирование HTTP-клиентов в Go: проверьте, как потребитель API обрабатывает статусы, неверные ответы и сетевые сбои.
- Арно Лоре, The Design of Web APIs: проектирование от задач потребителя и развитие контракта.
- Леонард Ричардсон и Майк Амундсен, RESTful Web APIs: ресурсы, представления и гипертекстовые переходы.
Точную семантику HTTP проверяйте по RFC, указанным в разделах статьи. Сервер и задания созданы для этого материала; это не примеры из перечисленных книг.
Теги: