Огляд REST. Частина 2: комунікація між клієнтом та сервером

Частина 1: що таке REST У цьому розділі ми докладно розглянемо, як відбувається комунікація між клієнтом і сервером. Принагідно ми розкриватимемо нові терміни і даватимемо до них пояснення. Щоб все було (стало) зрозуміло, розбиратимемо клієнт-серверну комунікацію на прикладі деякого RESTful додатка. Припустимо, ми розробляємо веб-додаток, який здатний зберігати інформацію про клієнтів та їх замовлення. Тобто. наша система здатна маніпулювати деякими сутностями: створювати їх, редагувати, видаляти, видавати інформацію про них. Цими сутностями будуть:

• clients - клієнти;
• orders - замовлення клієнтів;
• items – товари.

У REST архітектурі клієнти надсилають на сервер запити для отримання або модифікації даних, а сервери надсилають клієнтам відповіді на запити.

Запити

Клієнтські запити практично завжди зроблені за протоколом HTTP. Загалом, HTTP запити складаються з кількох складових:

• HTTP метод;
• Заголовок;
• URI;
• тіло запиту.

Нижче ми розглянемо докладніше кожну складову.

URI та Ресурси

Дані, які одержують чи змінюють клієнти за допомогою запитів, називають ресурсами. Основа клієнт-серверної взаємодії – маніпуляція над ресурсами. Ресурси в REST це все, чому можна дати ім'я. Це в якомусь сенсі як класи Java. У Java ми можемо створити клас для чого завгодно. Так і в REST - ресурсом може бути будь-що: користувач, документ, звіт, замовлення. Все це може бути абстракцією певної сутності, так і чимось конкретним, наприклад, файлом — картинкою, відео, анімацією, PDF файлом. У рамках нашого прикладу у нас є 3 ресурси:

• clients - клієнти;
• orders - замовлення клієнтів;
• items – товари.

Клієнти відправляють запити на так звані ендпоінти, або кінцеві точки (end point). Якщо говорити дуже просто, ендпоінт - це щось на зразок адресаи в мережі. Якщо заглиблюватися в суть, можна сказати, що ендпоінт – це URI: послідовність символів, що ідентифікує абстрактний чи фізичний ресурс. Uniform Resource Identifier – уніфікований ідентифікатор ресурсу. Іноді кінцеву точку, або URI називають шляхом (path) – шляхом до ресурсу. У рамках цієї статті ми будемо використовувати термін URI. У кожного конкретного ресурсу має бути унікальний URI. Відповідальність за те, щоб у кожного ресурсу завжди був свій URI, лежить на плечах розробника сервера. У нашому прикладі розробники це ми, тому робитимемо це так, як уміємо. Подібно до того, як у реляційній базі даних часто прийнято первинним ключем задавати деякий числовий ID, у REST у кожного ресурсу є свій ID. Часто буває так, що ID ресурсу REST збігається з ID запису в базі даних, в якій зберігається інформація про даний ресурс. URI в REST прийнято починати з множини іменника, що описує деякий ресурс. Наприклад, зі слова clients. Далі через слеш вказують ID - ідентифікатор певного клієнта. Приклади:

• /clients - URI всіх наявних клієнтів;
• /clients/23 - URI конкретного клієнта, а саме клієнта з ID = 23;
• /clients/4 - URI конкретного клієнта, саме клієнта з ID=4.

Але це ще не все. Ми можемо продовжити URI, додавши до нього замовлення:

• /clients/4/orders - URI всіх замовлень клієнта №4;
• /clients/1/orders/12 — URI замовлення №12 клієнта №1.

Якщо ми продовжимо цей ланцюжок і додамо ще й товари, отримаємо:

• /clients/1/orders/12/items — URI списку всіх товарів у замовленні №12, зробленого клієнтом №1.

З рівнями вкладеності головне робити URI інтуїтивно зрозумілими.

HTTP метод

Метод HTTP (англ. HTTP Method) — послідовність із будь-яких символів, крім керуючих та роздільників, яка вказує на основну операцію над ресурсом. Існує кілька загальноприйнятих методів HTTP. Перерахуємо ті з них, які найчастіше використовуються в RESTful сервісах:

• GET — служить отримання інформації про конкретний ресурс (через ID) чи колекції ресурсів;
• POST - служить для створення нового ресурсу;
• PUT служить для зміни ресурсу (через ID);
• DELETE — служить видалення ресурсу (через ID).

Заголовки

У запитах, як і у відповідях, присутні HTTP заголовки. Вони надсилається додаткова інформація про запит (або відповіді). Заголовки є парою ключ-значення. Список найпоширеніших заголовків можеш почитати на сторінці у Вікіпедії . Стосовно REST клієнти часто можуть надсилати у запиті до сервера заголовок Accept. Він потрібний, щоб дати серверу зрозуміти, в якому форматі клієнт очікує отримати від нього відповідь. Різні варіанти форматів представлені у так званому списку MIME типів. MIME(англ. Multipurpose Internet Mail Extensions — багатоцільові розширення інтернет-пошти) — специфікація для кодування інформації та форматування повідомлень таким чином, щоб їх можна було пересилати інтернетом. Кожен MIME тип складається з двох частин, що поділяються слешем - з типу та підтипу. Приклади MIME-типів для різних видів файлів:

• text - text/plain, text/css, text/html;
• image - image/png, image/jpeg, image/gif;
• audio - audio/wav, audio/mpeg;
• video - video/mp4, video/ogg;
• application - application/json, application/pdf, application/xml, application/octet-stream.

У запиту може бути заголовок:

Accept:application/json

Цей заголовок говорить серверу, що клієнт очікує отримати відповідь у форматі JSON.

Тіло запиту

Повідомлення, що пересилається клієнтом на сервер. Є у запиту тіло чи ні, залежить від типу запиту HTTP. Наприклад, запити GET і DELETE зазвичай не містять жодного тіла запиту. А ось PUT і POST можуть містити: тут вся справа у функціональному призначенні типу запиту. Адже для отримання даних та видалення по id (який передається в URL) не потрібно надсилати на сервер додаткові дані. Для створення нового ресурсу (запит POST) потрібно цей ресурс передати. Так само як і для модифікації існуючого ресурсу. У REST для передачі запиту найчастіше використовують формати XML або JSON. Найчастіше зустрічається JSON формат. Припустимо, ми хочемо надіслати на сервер запит, а в ньому створити новий ресурс. Якщо ти не забув, як приклад ми розглядали програму, яка керує замовленнями клієнтів. Припустимо, ми хочемо створити нового клієнта. У нашому випадку ми зберігаємо наступну інформацію про клієнтів: Ім'я Email Номер телефону Тоді тілом такого запиту може бути наступний JSON:

{
  "name" : "Amigo",
  "email" : "amigo@jr.com",
  "phone" : "+7 (191) 746-43-23"
}

Збираємо запити докупи

Отже, ми розглянули з тобою, з чого може складатися клієнтський запит. Наведемо кілька прикладів запитів з описом

Відповіді

Скажемо кілька слів про відповіді сервера. Відповідь зазвичай складається з наступних частин:

• код відповіді;
• заголовки;
• тіло відповіді.

Загалом заголовки відповідей мало чим відрізняються від заголовків запитів. До того ж деякі заголовки використовуються і у відповідях, і в запитах. З тілом відповіді теж, гадаю, все зрозуміло. У тілі часто повертається інформація, яку запитив клієнт. Може повертатись у тому ж форматі JSON інформація на GET запити. А ось остання частина трохи цікавіша.

Коди HTTP відповідей

Розглянемо докладніше коди HTTP відповідей. Наведемо цитату з Вікіпедії: Код стану HTTP (англ. HTTP status code) - частина першого рядка відповіді сервера при запитах протоколу HTTP. Він є цілим числом з трьох десяткових цифр. Перша цифра вказує клас стану. За кодом відповіді зазвичай слідує відокремлена пробілом пояснювальна фраза англійською мовою, яка роз'яснює людині причину саме такої відповіді. Приклади:

• 201 Created;
• 401 Unauthorized;
• 507 Insufficient Storage.

Клієнт дізнається за кодом відповіді про результати його запиту та визначає, які дії йому робити далі. Коди відповідей поділяються на кілька груп:

• 1ХХ - інформаційні;
• 2ХХ - інформують про випадки успішного прийняття та обробки запиту клієнта;
• 3ХХ - повідомляють клієнту, що для успішного виконання операції необхідно зробити інший запит, як правило, по іншому URI;
• 4ХХ - помилка клієнта. Наприклад, неправильно складений запит або широко відомий код 404 Not Found, яка може виникнути, коли клієнт запитує неіснуючий ресурс;
• 5ХХ - помилка сервера. Повертається клієнту у разі невдалого виконання операції з вини сервера.

Докладніше про всі коди можна почитати тут . Частина 1: що таке REST Частина 3: створення RESTful сервісу на Spring Boot