Разобрать HTTP-запрос и ответ на части и спроектировать адреса REST-ресурсов кейса: существительные во множественном числе, иерархия, параметры пути и запроса.
Запрос, ответ и ресурсы
Запрос, ответ и ресурсы
Повторение из курса по тестированию: HTTP-запрос состоит из метода, адреса (URI: путь и параметры запроса), заголовков и тела, ответ — из кода статуса, заголовков и тела. HTTP не помнит прошлых запросов (stateless): каждый запрос несёт всё нужное серверу, включая токен.
REST — архитектурный стиль (Рой Филдинг, 2000), а не формат данных: у каждого ресурса свой адрес, у методов один смысл для всех ресурсов (единый интерфейс), сервер не хранит состояние диалога, ответы могут кэшироваться. Данные идут в JSON, XML или другом формате. «REST = JSON» — заблуждение: JSON просто встречается чаще.
Правила адресов:
• ресурс — существительное во множественном числе: /orders;
• конкретный ресурс — по идентификатору: /orders/9001;
• вложенный — если принадлежит родителю: /orders/9001/items;
• действие выражает метод, а не глагол в пути: не /getOrder, не /createOrder. Исключение — действие вне «создать, прочитать, изменить, удалить», например отмена: POST /orders/9001/cancel (подробно — в следующем уроке).
Параметр пути (path) указывает, какой ресурс нужен: 9001 в /orders/9001. Параметр запроса (query) стоит после «?» и фильтрует, сортирует или листает список: /orders?customerId=42&status=delivered — заказы клиента 42 в статусе delivered (доставлен).
Заголовки, которые аналитик пишет в контракт, — в таблице ниже. Позже к ним добавится Idempotency-Key.
Хороший и плохой адрес
| Задача | Так | Не так |
|---|---|---|
| получить заказ | GET /v1/orders/9001 | GET /v1/getOrder?id=9001 |
| создать заказ | POST /v1/orders | POST /v1/orders/create |
| позиции заказа | GET /v1/orders/9001/items | GET /v1/orderItems?order=9001&all=true |
| оплаченные заказы | GET /v1/orders?status=paid | GET /v1/orders/paid |
Заголовки в контракте
| Заголовок | Что передаёт |
|---|---|
| Content-Type | формат тела: application/json |
| Accept | в каком формате клиент ждёт ответ |
| Authorization | токен клиента |
| Location | адрес созданного ресурса: /v1/orders/9001 |
| Retry-After | через сколько можно повторить запрос |
Конспект урока
Запрос, ответ и ресурсы
Повторение из курса по тестированию: HTTP-запрос состоит из метода, адреса (URI: путь и параметры запроса), заголовков и тела, ответ — из кода статуса, заголовков и тела. HTTP не помнит прошлых запросов (stateless): каждый запрос несёт всё нужное серверу, включая токен.
REST — архитектурный стиль (Рой Филдинг, 2000), а не формат данных: у каждого ресурса свой адрес, у методов один смысл для всех ресурсов (единый интерфейс), сервер не хранит состояние диалога, ответы могут кэшироваться. Данные идут в JSON, XML или другом формате. «REST = JSON» — заблуждение: JSON просто встречается чаще.
Правила адресов:
• ресурс — существительное во множественном числе: /orders;
• конкретный ресурс — по идентификатору: /orders/9001;
• вложенный — если принадлежит родителю: /orders/9001/items;
• действие выражает метод, а не глагол в пути: не /getOrder, не /createOrder. Исключение — действие вне «создать, прочитать, изменить, удалить», например отмена: POST /orders/9001/cancel (подробно — в следующем уроке).
Параметр пути (path) указывает, какой ресурс нужен: 9001 в /orders/9001. Параметр запроса (query) стоит после «?» и фильтрует, сортирует или листает список: /orders?customerId=42&status=delivered — заказы клиента 42 в статусе delivered (доставлен).
Заголовки, которые аналитик пишет в контракт, — в таблице ниже. Позже к ним добавится Idempotency-Key.