Модуль 11 · Урок 41 із 58
HTTP contract: request, response, methods і status codes
HTTP — не просто спосіб отримати JSON. Це контракт між клієнтом, сервером і посередниками: method формулює намір, status описує результат, headers несуть metadata, а representation передає стан ресурсу.
Безпечна HTTP-практика модуля 11
Пакет містить synthetic fixtures, loopback-only HTTP server, bounded urllib client, Problem Details і contract tests. Тести виконують реальні request/response лише на 127.0.0.1 без Internet, персональних чи production-даних, credentials і production endpoints.
Повідомлення має структуру й семантику
Request містить method, target URI, fields у headers і необов’язковий content. Response повертає status code, fields і content. Кожна частина має власну роль: query parameter фільтрує або модифікує запит, Content-Type описує надіслане представлення, а Accept повідомляє, які media types клієнт готовий опрацювати.
Method — частина публічного contract
GET читає representation, POST передає content для обробки, PUT замінює або створює стан за відомим target, PATCH застосовує опис змін, а DELETE просить видалити association ресурсу. Method не обирають за зручністю роутера.
| Властивість | Що означає | Наслідок |
|---|---|---|
| Safe | Клієнт не просить змінити стан | GET не використовують як кнопку видалення |
| Idempotent | Повтор того самого intent має той самий intended effect | Retry потребує доказу, не здогадки |
| Cacheable | Response може бути reuse за правилами | Cache directives і validators мають значення |
Idempotent не означає «response завжди однаковий»: logs, timestamps або concurrent state можуть змінитися. Йдеться про intended effect повтореного request.
Status code описує результат
Категорії 2xx, 3xx, 4xx і 5xx розділяють success, redirection, client-side condition та server failure. Конкретний code має відповідати факту: 200 для звичайного success із content, 201 після створення з посиланням на resource, 204 без content, 400 для некоректного request, 404 для відсутнього resource, 409 для conflict із поточним state.
HTTP 200 із полем error — слабкий contract
Generic clients, monitors і caches читають status line. Domain detail додають у representation, але не підмінюють нею HTTP semantics.
Representation потребує media type
JSON-об’єкт є representation, а не самим resource. Клієнт перевіряє status і Content-Type до parsing, декодує bytes за узгодженим charset і не припускає, що будь-який success містить JSON. Для write request він явно ставить Content-Type: application/json; для очікуваної відповіді — Accept.
GET /api/tasks?status=open&limit=20 HTTP/1.1
Host: api.example.test
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, max-age=30Validators захищають від зайвої передачі й конфліктів
ETag або Last-Modified може валідовувати cached representation. Conditional GET із If-None-Match дозволяє 304 Not Modified без повторного content. Для concurrent write precondition на кшталт If-Match допомагає не затерти новішу версію, але його policy треба явно визначити.
- Назвіть resource і representation.
- Оберіть method за semantics.
- Визначте success і failure statuses.
- Зафіксуйте request/response fields та media types.
- Опишіть retry, caching і concurrency assumptions.
Методичні джерела
Урок, сценарії, пояснення й вправи створені SEOWORK. Посилання ведуть на стандарти та авторитетну офіційну документацію.
Закріпіть матеріал уроку
Три сценарні питання. Для зарахування уроку потрібно дати щонайменше дві правильні відповіді.