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

Що таке REST

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

А тепер теж найбільш наочно:

Відсутність додаткових внутрішніх прошарків означає передачу даних у тому вигляді, як і самі дані. Тобто. ми не загортаємо дані в XML, як це робить SOAP та XML-RPC, не використовуємо AMF, як це робить Flash і т.д. Просто надаємо самі дані.

Кожна одиниця інформації однозначно визначається URL – це означає, що URL є первинним ключем для одиниці даних. Тобто. наприклад, третя книга з книжкової полиці матиме вигляд /book/3, а 35 сторінка в цій книзі - /book/3/page/35. Звідси й виходить заданий формат. Причому зовсім не має значення, в якому форматі знаходяться дані за адресою /book/3/page/35 – це може бути і HTML, і копія відсканована у вигляді jpeg-файлу, і документ Microsoft Word.

Як відбувається управління інформацією сервісу – це повністю й грунтується на протоколі передачі. Найбільш поширений протокол звичайно ж є HTTP. Так ось, для HTTP дія над даними визначається за допомогою методів: GET (отримати), PUT (додати, замінити), POST (додати, змінити, видалити), DELETE (видалити). Таким чином, дії CRUD (Create-Read-Updtae-Delete) можуть виконуватися як з усіма чотирма методами, так і лише за допомогою GET та POST.

Ось як це виглядатиме на прикладі:

GET /book/ - отримати список усіх книг
GET /book/3/ - одержати книгу номер 3
PUT /book/ - додати книгу (дані у тілі запиту)

DELETE /book/3 – видалити книгу

ВАЖЛИВЕ ДОДАТК:Існують звані REST-Patterns , які відрізняються зв'язуванням HTTP-методів про те, що роблять. Зокрема різні патерни по-різному розглядають POST і PUT. Однак, PUT призначений для створення, реплейсу чи апдейту, для POST це не визначено (The POST operation is very generic and no specific meaning can be attached to it). Тому мій приклад буде правильним і в такому вигляді, і як якщо поміняти місцями POST і PUT.

Взагалі, POST може використовуватись одночасно для всіх дій зміни:
POST /book/ – додати книгу (дані у тілі запиту)
POST /book/3 – змінити книгу (дані у тілі запиту)
POST /book/3 – видалити книгу (тіло запиту порожнє)

Це дозволяє іноді оминати неприємні моменти, пов'язані з неприйняттям PUT та DELETE.

Використання REST для побудови Web-сервісів.

Для кожної одиниці інформації визначається 5 дій. А саме:

GET /info/ (Index)- Отримує список всіх об'єктів. Зазвичай, це спрощений перелік, тобто. містить лише поля ідентифікатора та назви об'єкта, без інших даних.

GET /info/(id) (View)- Отримує повну інформацію про об'єкт.

PUT /info/або POST /info/ (Create)- Створює новий об'єкт. Дані передаються в тілі запиту без застосування кодування, навіть urlencode. У PHP тіло запиту може бути отримано в такий спосіб:

Function getBody() (
if (!isset($HTTP_RAW_POST_DATA))
$HTTP_RAW_POST_DATA = file_get_contents("php://input");
return $HTTP_RAW_POST_DATA;
}

POST /info/(id)або PUT /info/(id) (Edit)– змінює дані з ідентифікатором (id), можливо, замінює їх. Дані також передаються в тілі запиту, але на відміну від PUT тут є певний нюанс. Справа в тому, що POST-запит передбачає наявність urldecoded-post-data. Тобто. якщо не застосовувати кодування – це порушення стандарту. Тут хто як хоче – деякі не звертають уваги на стандарт, деякі використовують якусь post-змінну.

DELETE /info/(id) (Delete)– видаляє дані із ідентифікатором (id).

Ще раз зазначу, що в нашому прикладі /info/ - може і базуватися на якійсь іншій інформації, що може бути (і має бути) відображено в URL:

/data/4/otherdata/6/info/3/ … тощо.

Які можна зробити з цього висновки:

Як видно, архітектура REST дуже проста в плані використання. На вигляд запиту відразу можна визначити, що він робить, не розбираючись у форматах (на відміну від SOAP, XML-RPC). Дані передаються без застосування додаткових шарів, тому REST вважається менш ресурсомістким, оскільки не треба парсити запит, щоб зрозуміти, що він повинен зробити і не треба перекладати дані з одного формату в інший.

Практичне застосування.

Архітектура REST дозволяє серйозно спростити це завдання. Звичайно в дійсності, того що описано мало, адже не можна будь-кому давати можливість змінювати інформацію, тобто потрібна ще авторизація та автентифікація. Але це досить легко дозволяється за допомогою різного типу сесій або просто HTTP Authentication.

REST API (Representational State Transfer), або веб-служби RESTful, що це? REST у перекладі з англійської «репрезентативна передача стану». Це спосіб забезпечення взаємодії між комп'ютерними системами Інтернету. REST-сумісні веб-служби, що дозволяють системам, що запитують, отримувати доступ до текстових уявлень веб-ресурсів і керувати ними, використовуючи єдиний і зумовлений набір операцій. Існують інші форми веб-служб, які містять свої власні довільні набори операцій, наприклад WSDL і SOAP.

REST API: що це таке? Визначення поняття

Веб-ресурси спочатку були визначені у Всесвітньому павутинні як документи або файли, ідентифіковані їх URL-адресами. Сьогодні вони мають набагато більш загальне та абстрактне визначення, що охоплює кожен предмет чи сутність, які можуть бути ідентифіковані, названі, адресовані чи оброблені в Мережі. У веб-службі REST API запити, отруєні в URI-ресурсі, викликають відповідь, яка може бути оформлена в XML, HTML, JSON або будь-якому іншому форматі. Відповідь може підтвердити, що деякі зміни були внесені в ресурс, що зберігається, також надати гіпертекстові посилання на інші пов'язані ресурси та їх колекції. Використання HTTP як найпоширенішого протоколу відноситься до типів доступних операцій, визначених командами PUT, DELETE, HTTP GET, POST.

Використовуючи протоколи без урахування стану та стандартні операції, системи REST націлені на швидку продуктивність, надійність та здатність до зростання шляхом повторного використання компонентів, якими можна керувати та які можна оновлювати, не торкаючись системи загалом. Використання REST часто краще, ніж більш важкий стиль SOAP (Simple Object Access Protocol), оскільки REST не використовує смуги пропускання, що робить його більш придатним для використання в Інтернеті. Для підходу SOAP потрібно записувати або використовувати надану серверну програму (для обслуговування даних) і клієнтську програму (для запиту даних).

Історія технології

Термін «репрезентативна передача стану» було введено та визначено у 2000 році Роєм Філдінгом у його дисертації «Архітектурні стилі та дизайн мережевих архітектур програмного забезпечення». Він виробив архітектурний стиль REST паралельно із HTTP 1.1 1996-1999 років, заснований на існуючому проекті HTTP 1.0 1996 року. У ретроспективному погляді на розвиток технології Філдінг сказав, що протягом процесу стандартизації HTTP він був покликаний захищати вибір дизайну в Інтернеті. Це дуже складне завдання в рамках процесу, що приймає пропозиції від будь-кого на тему, яка швидко стає центром усієї галузі.

Філдінг мав коментарі від більш ніж 500 розробників, багато з яких відмінні інженери з багаторічним досвідом. Він повинен був пояснити все, починаючи з абстрактних понять веб-взаємодії і закінчуючи точними деталями синтаксису HTTP. Цей процес відточував його модель до основного набору принципів, властивостей та обмежень, які тепер називають REST.

Переваги

Особливості стилю REST впливають на такі архітектурні властивості:

• Продуктивність - взаємодія компонентів є домінуючим властивістю у сприйнятті користувачами продуктивності та результативності мережі.
• Масштабованість для підтримки максимальної кількості компонентів, тестування REST API та взаємодії між ними.
• Простота єдиного інтерфейсу та авторизації REST API.
• Модифікованість компонентів задоволення мінливих потреб (навіть під час роботи програми).
• Видимість зв'язку між складовими та сервісними агентами.
• Можливість переносити компоненти, переміщаючи їхній програмний код з даними.
• Надійність - висока стійкість до відмови при наявності збоїв у складі, роз'ємів або даних.

Зумовлено поділ проблем між клієнтами тим, що цей REST API дозволяє спрощувати реалізацію компонентів, зменшує складність семантики конектора, підвищує ефективність налаштування продуктивності та підвищує масштабованість чистих серверних компонентів. Складні системні обмеження дозволяють посередникам-проксі, шлюзам та брандмауерам впроваджуватись у різних точках зв'язку без зміни інтерфейсів між компонентами, що дозволяє їм здійснювати REST-переклад повідомлень або підвищувати продуктивність за допомогою широкомасштабного загального кешування. Прикладом REST API є той факт, коли взаємодія не залежить від стану запитів, стандартні методи та типи медіа використовуються для позначення семантики та обміну інформацією, а відповіді явно вказують на кешування.

Формальні та архітектурні обмеження

Шість керівних обмежень характеризують систему RESTful. Вони обмежують способи, якими сервер може обробляти та приймати запити клієнтів. Діючи в рамках цих обмежень, служба отримує бажані нефункціональні властивості, такі як продуктивність, масштабованість, простота, мінливість, видимість, мобільність та надійність. Якщо служба порушує будь-які необхідні обмеження, її не можна вважати RESTful.

Перші обмеження відносяться до архітектурного стилю клієнт-сервер. Поділ проблем інтерфейсу користувача з проблемами зберігання даних покращує переносимість інтерфейсу користувача на декількох платформах. Він також покращує масштабованість за рахунок спрощення серверних компонентів. Можливо, найбільш значущим для Мережі є те, що поділ дозволяє компонентам розвиватися самостійно, тим самим підтримуючи вимоги інтернет-масштабу до багатьох організаційних доменів.

Безпека

REST не надає вбудованої підтримки безпеки. Це дуже важливо при проектуванні веб-сервісів REST – вимоги безпеки та проектування виконуються заздалегідь. Веб-сервіси REST використовують HTTP PUT та DELETE з CRUD-операцій. PUT і DELETE не підтримуються багатьма браузерами і найчастіше відключені на рівні сервера через можливе порушення конфіденційності. Якщо він не налаштований належним чином на рівні сервера і клієнта, будь-який сторонній користувач зможе створити ресурс за допомогою методу PUT або знищити використовуваний ресурс DELETE. Під час розробки вимог безпеки для веб-сервісів слід враховувати ці моменти.

Архітектурні елементи

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

Ресурс – це об'єкт (логічний чи фізичний), доступний в Інтернеті. Це може бути документ, який зберігається у файловій системі сервера або рядок у таблиці бази даних. Кінцевий користувач взаємодіє з ресурсом задля досягнення певної мети. Для проектування системи за допомогою REST розробник повинен думати про бізнес-об'єкти як ресурси та про те, як вони можуть бути адресовані.

URI – унікально ідентифікує ресурс. Цей параметр робить адресний ресурс і може бути змінений. Ресурси змінюються за допомогою протоколу програми - такого як HTTP.

Подання - стану ресурсу на момент часу. Клієнт отримує подання ресурсу за запитом URI. Вигляд ресурсу може бути закодований в одному або декількох форматах, що передаються, таких як XML, HTML, JSON, RSS, REST API java. Ці формати можна узгодити з допомогою механізму узгодження контенту.

Посилання - дозволяє програмі виконувати перехід з одного стану в інший. Кожен ресурс має бути підключений до інших ресурсів. Подання має запропонувати посилання на наступний перехід. Добре пов'язана програма дозволяє користувачу самостійно відкрити інтерфейс.

Конектор

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

Клієнт та сервер є основними REST-конекторами. Клієнт ініціює запит, а сервер його обробляє.

Кеш – ще один вид роз'єму. Кешування може бути реалізовано на клієнтських, серверних чи проміжних рівнях. Це зменшує час очікування та використання мережі.

Компоненти

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

User-Agent – ​​використовує клієнтський з'єднувач для ініціювання запиту.

Origin-сервер – використовує серверний конектор для відповіді на запит.

Проксі - посередник, що використовується на стороні клієнта для інкапсуляції інтерфейсу іншими службами. Він також виконує переклад даних та захист.

Шлюз – посередник, який використовується на сервері для забезпечення інкапсуляції інтерфейсу іншими службами.

Перспективи розвитку

Завжди актуальним є питання: REST API — що це для сучасних інтернет-технологій? REST – основа сучасної веб-архітектури, яка розвивається шляхом аналізу недоліків вже існуючих стилів та запровадження нових доповнень до неї.

Цілі REST API - що це? Це прагнення використовувати існуючі стилі з координованим набором обмежень для мінімізації мережного зв'язку та максимізувати незалежну еволюцію компонентів для досягнення масштабованості. Це нова архітектура гіпермедіа. З появою смартфонів, планшетів тощо гаджетів впроваджуватиметься мережа та її масштабованість.

RESTful API може створюватися як для сторонніх сервісів. Він може використовуватися односторінковими програмами для роботи з бек-ендом. Ось кілька основних моментів, які потрібно знати під час проектування інтерфейсу.

URLs та дії

Ключовим принципом REST є поділ вашого API на логічні ресурси. Управління цими ресурсами відбувається за допомогою HTTP-запитів з відповідним методом – GET, POST, PUT, PATCH, DELETE.

Ресурс повинен описуватися іменником у множині. Дії над ресурсами зазвичай визначаються стратегією CRUD і відповідають HTTP-методам наступним чином:

• GET /api/users – отримати список користувачів;
• GET /api/users/123 - отримати вказаного користувача;
• POST /api/users – створити нового користувача;
• PUT /api/users/123 - оновити усі дані вказаного користувача;
• PATCH /api/users/123 – частково оновити дані користувача;
• DELETE /api/users/123 - видалити користувача.

Якщо ресурс існує тільки в контексті іншого ресурсу, URL може бути складовим:

• GET /api/posts/9/comments - отримати список коментарів до запису №9;
• GET /api/posts/9/comments/3 - отримати коментар №3 до запису №9.

Коли дію над об'єктом відповідає CRUD операції, його можна як складовий ресурс:

• POST /api/posts/9/like - відзначити запис №9 як уподобаний;
• DELETE /api/posts/9/like - зняти позначку «сподобалося» із запису №9.

Дії зі створення та оновлення ресурсів мають повертати ресурс

Методи POST, PUT або PATCH можуть змінювати поля ресурсу, які не були включені до запиту (наприклад, ID, дата створення або дата оновлення). Щоб не примушувати користувача API виконувати ще один запит на отримання оновлених даних, такі методи мають повернути їх у відповіді.

Фільтри, сортування та пошук

Будь-які параметри HTTP-запиту можуть бути використані для уточнення запиту або сортування даних.

• GET /api/users?state=active – список активних користувачів;
• GET /api/tasks?state=open&sort=priority,-created_at - список невиконаних завдань, відсортованих за пріоритетом та датою створення (спочатку нові завдання).

Посторінкова навігація

Коли потрібно у відповідь на запит списку об'єктів додати інформацію про сторінкову навігацію, варто скористатися заголовком HTTP Link , а не додавати обгортки даним.

Приклад заголовка:

Link: ; rel="next", ; rel="prev", ; rel="first", ; rel="last"

Можливі значення rel:

• next – наступна сторінка результатів;
• prev – попередня сторінка результатів;
• first – перша сторінка результатів;
• last – остання сторінка результатів.

Важливо дотримуватися цих значень, а не конструювати власні URL тому, що іноді посторінкова навігація може ґрунтуватися на складних правилах, а не простому переборі сторінок.

Перевизначення HTTP-методу

Для сумісності з деякими серверами або клієнтами, які не підтримують інші HTTP-методи, крім GET і POST, може бути корисною їхня емуляція. Значення методу передається в заголовку X-HTTP-Method-Override, а сам він виконується як POST-метод. GET-запити не повинні змінювати стан сервера!

Коди HTTP-статусу

• 200 OK – відповідь на успішний запит GET, PUT, PATCH або DELETE.
• 201 Created - відповідь на POST запит, у результаті якого відбулося створення нового об'єкта. Відповідь також має супроводжуватися заголовком Location , що вказує на URL ресурсу.
• 204 No Content – ​​відповідь на успішно виконаний запит, який нічого не повертає (наприклад, DELETE).
• 404 Not Found - запитуваний об'єкт не знайдено.
• 500 Internal Server Error – помилка на сервері.

У разі помилок, у відповіді може бути налагоджувальна інформація для розробників, якщо це можливо.

Деякі скажуть:

«Це API, який використовує HTTP-запити для

GET, PUT, POSTі DELETE ".

Багато хто також скаже:

«Йдеться про визначення ресурсів за допомогою URI»

Інші кричатимуть:

На закінчення можна сказати:

«В принципі, це просто API, який використовує HTTPправильно!»

Деякі з цих тверджень помилкові,

Деякі частково вірні,

але це не має значення,

Бо вони всі упускають суть.

Щоб мати можливість розробляти API RESTful,

По перше,

Що таке REST?

Що таке REST?

REST це:

Виразно не HTTP

Чи не протокол

Чи не специфікація

Ось чому навколо REST APIs так багато суперечок.

І все таки...

REST – це стиль архітектури.

О, гаразд… але що таке стиль архітектури?

Стиль архітектури

Бажана архітектура

Це просто архітектура плюс набір обмежень, що застосовуються до архітектури, що створює бажану архітектуру.

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

REST виступає за подання стану передачі

Це було записано Роєм Філдінгом у його докторській дисертації у 2000 році, де він описав існуючу та сучасну веб-архітектуру як абстракцію.

Назва була покликана викликати уявлення про те, як поводиться добре розроблений веб-додаток.

Рой описав REST на простому прикладі:

Розглянемо мережу веб-сторінок як віртуальну машину станів.

Кожна сторінка представляє стан:

1. По-перше, користувач отримує перший стан у вигляді індексного стану.

2. Потім користувач переходить через програму, вибираючи посилання (тут посилання на сторінку)

3. Результат передачі наступного стану користувачеві.

REST досі не HTTP

Звичайно, ще 2000 року мережа вже працювала на HTTP, і Рой зі своїми колегами-інженерами багато працювали над цим.

Однак REST не визначає конкретні деталі реалізації системи і не визначає синтаксис протоколу.

Цілком можливо мати архітектуру RESTful поверх протоколів, відмінних від HTTP.

Наприклад, CoAP (протокол обмеженого застосування) є протоколом RESTful для вбудованих пристроїв (Internet of Things) і призначений для використання мінімальних ресурсів як у пристрої, так і в мережі.

То навіщо використовувати REST?

Всесвітнє павутиння засноване на архітектурі REST.

Тому, якщо ви створюєте API-інтерфейс non-RESTful, який використовуватиметься в Інтернеті, то ви отримаєте неоптимальну систему. Не оптимальний щодо оптимізованої архітектури.

Це важливо відзначити, оскільки не-RESTful API може бути неоптимальним у мережевій архітектурі, але оптимальним для інших проблем. Наприклад, сучасні інтерфейсні програми можуть мати дуже специфічні потреби, отже, зростає кількість бібліотек збору даних, таких як GraphQL або Falcor.

Отже, коли це API RESTful?

API є RESTful, коли вона постійно діє під обмеженнями REST.

REST визначає 6 обмежень для досягнення бажаної оптимізації системи:

1. Клієнт-сервер

Це обмеження ґрунтується на принципі поділу інтересів.

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

2. Без громадянства

Зв'язок між клієнтом та сервером має бути без громадянства. Це означає, що кожен запит від клієнта до сервера повинен містити всю необхідну інформацію для завершення транзакції.

Основною перевагою цього обмеження є те, що система здатна масштабуватись краще, тому що серверу не потрібно зберігати стан клієнта між запитами. Відсутність необхідності запам'ятовувати інформацію про стан клієнта звільняє ресурси сервера, тому може обслуговувати більше клієнтів одночасно.

Найбільш ефективним мережним запитом є той, який не використовує мережу.

Коли ми створюємо наш API, він не повинен ігнорувати кешування.

4. Правильний інтерфейс

Щоб мати ефективне кешування мережі, компоненти повинні мати можливість взаємодіяти через єдиний інтерфейс. З єдиним інтерфейсом корисне навантаження може передаватися у стандартній формі.

4.1. Ідентифікація ресурсів

Це означає, що будь-яка інформація, яка може бути названа, може бути ресурсом (зображення, документ або навіть набір інших ресурсів)

4.2. Маніпулювання ресурсами через уявлення

Ресурс може бути представлений у різний спосіб.

Наприклад, HTML, XML, JSON або навіть JPEG-файл.

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

4.3 По-третє, самоописові повідомлення

Це означає, що ресурс може бути описаний у повідомленні запиту, а сервер може відповідати описовим повідомленням про стан. Так, HTTP-заголовки та коди відповідей є гарними реалізаціями для цього правила.

4.4. Hypermedia має бути двигуном стану програми

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

Як ви можете бачити, багато цих правил можуть бути реалізовані в протоколі HTTP. Тому, коли API використовує HTTP правильно, це величезний крок до того, щоб стати RESTful.

5. Багаторівнева система

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

Однією з переваг багаторівневої системи є те, що посередники можуть перехоплювати трафік клієнт-сервер для певних цілей/ Наприклад, для кешування.

6. Код на вимогу

Це необов'язкове обмеження та дозволяє клієнтам завантажувати програми для виконання на стороні клієнта. Найкращий приклад для цього – інтерфейсні JavaScript-додатки. Це може здатися нам зараз дуже очевидним, але в ранньому віці Інтернету це була концепція, що еволюціонує, і це корисна частина інтернет-архітектури.

Отже, як створити REST API?

Правильно використовувати HTTP

Якщо ви будуєте API RESTful, використовуйте протокол RESTful. Для Інтернету HTTP-протокол є певним вибором. Створіть API для правильного використання HTTP.

Створіть єдиний інтерфейс

Порівняйте свої концепції з ресурсами та призначте відповідні ідентифікатори для кожного з них. Найпростішим прикладом може бути служба бази даних користувачів. У такій службі ми можемо назвати два ресурси; Користувачів та користувачів (ресурс збору). Ці ресурси можуть бути ідентифіковані з URI / users та / user / (id) URI вашого інтерфейсу API.

Керуйте своїм API-гіперпосиланнями

Пам'ятайте про архітектуру REST

Для мене головне звільнення від створення RESTful API полягає в тому, наскільки важливо розуміти Інтернет та його базову архітектуру. Ми можемо або скористатися цією оптимізацією, або ми можемо її ігнорувати.

Якщо у вас виникли будь-які питання, запрошуємо на наші

Дякую, що прочитали мій пост.
Зворотній зв'язок та думки завжди вітаються у розділі коментарів.

Здрастуйте, дорогі читачі! Перш ніж ви почнете читати цю статтю, я хотів би описати цілі її створення і розповісти, що спонукало мене до її написання.

На одному з проектів нашої компанії виникла потреба спроектувати серверний додаток у стилі REST. Спочатку нам здавалося, що це досить просте завдання і для її вирішення вистачить лише власного досвіду.

Але коли стартував процес розробки архітектури та приведення REST-сервісів до єдиного стилю, у нас з колегами почали виникати спірні питання та з'являтися різні точки зору на реалізацію того чи іншого аспекту. Тут ми зрозуміли, що необхідно відкрити гугл і звернутися до допомоги колективного розуму, вивчити найкращі практики, які необхідно використовувати при проектуванні RESTful програми.

Ця стаття буде корисною для тих людей, які вже мають деякий досвід роботи з веб-додатками (і можливо з REST-сервісами), але потребують закріплення та стандартизації отриманих знань.

Визначення

Для початку потрібно визначитися, що таке REST. Вікіпедія дає це питання наступну відповідь. REST (Representational State Transfer- «Передача стану уявлення») - архітектурний стиль взаємодії компонентів розподіленого додатку в мережі. REST є узгодженим набором обмежень, що враховуються при проектуванні розподіленої гіпермедіа-системи.

Своїми словами я пояснив би поняття REST як "набір рекомендацій, який дозволяє уніфікувати взаємодію клієнтських і серверних додатків".
У цій статті я постараюся розповісти про ці «рекомендації», які допоможуть проектувати та створювати REST-сервіси згідно з загальноприйнятими практиками.

Також слід розуміти, що таке REST-сервіс. Я дав би визначення REST-сервісу, як “точка взаємодії клієнтської програми з сервером”. Говорячи Java термінологією - це сервлет, який клієнт посилає запит.

Проблематика

Але перш ніж починати описувати правила, я хотів би донести думку про те, що REST – це не стандарт, тому немає єдиних суворих правил, яких варто дотримуватись. Це означає, що досі немає повної узгодженості про те, які рішення краще застосовувати у тій чи іншій ситуації. Дуже часто заходять суперечки про те, які методи HTTP використовувати і який HTTP код повертати в кожній конкретній ситуації.

Назва сервісу

Для початку потрібно вибрати ім'я для REST сервісу. Під ім'ям сервісу я маю на увазі його шлях в URI запиті. Наприклад, http://my-site.by/api/rest/service/name. Для вибору імені нам потрібно розуміти, що таке “ресурси” в архітектурі REST.

Подання ресурсу

У термінології REST будь-що може бути ресурсом - HTML-документ, зображення, інформація про конкретного користувача і т.д. Якщо ресурс є деяким об'єктом, його легко уявити, використовуючи деякий стандартний формат, наприклад, XML або JSON. Далі сервер може надіслати даний ресурс, використовуючи вибраний формат, а клієнт зможе працювати з отриманим від сервера ресурсом, використовуючи цей формат.

Приклад подання ресурсу "профіль" у форматі JSON:

"id" :1 ,

"name" :"Mahesh" ,

"login" :"manesh"

REST не накладає явних обмежень на формат, який має бути використаний для представлення ресурсів, але є низка правил, які слід дотримуватися при розробці формату, який буде використовуватися для представлення ресурсу:

• Клієнт та сервер повинні “розуміти” та мати можливість працювати з вибраним форматом.
• Ресурс можна повністю описати за допомогою вибраного формату незалежно від складності ресурсу.
• Формат має передбачати можливість надання зв'язків між ресурсами.

Приклад подання ресурсу "замовлення" та його зв'язку з ресурсом "профіль":

id: 11254 ,

currency: "EUR" ,

amount: 100 ,

profile: (

id: 11 ,

uri: "http://MyService/Profiles/11"

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

Звернення до ресурсу

Кожен ресурс має бути унікально позначений постійним ідентифікатором. "Постійний" означає, що ідентифікатор не зміниться за час обміну даними, і навіть коли зміниться стан ресурсу. Якщо ресурсу надається інший ідентифікатор, сервер повинен повідомити клієнта, що запит був невдалим і дати посилання на нову адресу. Кожен ресурс однозначно визначається URL-адресою. Це означає, що URL є первинним ключем для одиниці даних. Тобто, наприклад, друга книга з книжкової полиці матиме вигляд /books/2 , а 41 сторінка у цій книзі - /books/2/pages/41 . Звідси й виходить заданий формат. Причому зовсім не має значення, у якому форматі знаходяться дані за адресою /books/2/pages/41 – це може бути HTML, і відсканована копія у вигляді jpeg-файлу, і документ Word.

Рекомендується при визначенні імені REST-сервісу використовувати імена ресурсів у множині. Такий підхід дозволяє додавати нові REST-сервіси лише розширюючи імена існуючих. Наприклад, сервіс /books поверне нам список усіх книг, /books/3 поверне інформацію про 3-ю книгу, а сервіс /books/3/pages поверне всі сторінки третьої книги.

Для сервісів, які виконують якісь специфічні дії над ресурсом, є два підходи для вказівки дії: в імені сервісу або в його параметрах. Наприклад, /books/3/clean або /books/3?clean . Я віддаю перевагу першому варіанту, тому що зазвичай такі сервіси не рідко використовують POST методи, які не підтримують передачу параметрів в URl, що робить сервіс, на мій погляд, не дуже читабельним. Використовуючи визначення типу дії у імені сервісу, ми робимо наш сервіс більш розширюваним, оскільки він залежить від типу HTTP методу.

Також дуже не рекомендується використовувати імена, що включають кілька слів і описують бізнес складову сервісу (як це рекомендується робити при іменуванні java методів). Наприклад, замість /getAllCars краще зробити метод /cars . Якщо ж метод не можна описати одним словом, то необхідно застосовувати єдиний стиль роздільників, я зазвичай використовую '-', що є найбільш популярним підходом. Наприклад, /cars/3/can-sold.

Детальніше про проектування назв REST-сервісів можна прочитати в

HTTP методи

У REST використовуються 4 основні HTTP методи: GET, POST, PUT, DELETE. Найчастіше кожен із методів служить до виконання зумовленого йому дії з CRUD ( c reate, r ead, u pdate, d elete – «створення, читання, оновлення, видалення»).
POST – create, GET – read, PUT – update, DELETE – delete.

ВАЖЛИВЕ ДОДАТК: Існують звані REST-Patterns, які відрізняються зв'язуванням HTTP-методів про те, що роблять. Зокрема різні патерни по-різному розглядають POST і PUT. Однак, PUT призначений для створення, заміни або оновлення, для POST це не визначено. Тому іноді POST та PUT можна поміняти місцями. Але в більшості випадків POST використовують для створення, а PUT для редагування, і трохи пізніше поясню чому.

Наведу кілька прикладів використання різних методів взаємодії з ресурсами.

• GET /books/- Отримує список всіх книг. Зазвичай, це спрощений перелік, тобто. містить лише поля ідентифікатора та назви об'єкта, без інших даних.
• GET /books/(id)- Отримує повну інформацію про книгу.
• POST /books/- Створює нову книгу. Дані передаються в запиті.
  PUT /books/(id)– змінює дані про книгу з ідентифікатором (id), можливо, замінює їх. Дані також передаються у запиті.
• OPTIONS /books- Отримує список підтримуваних операцій для зазначеного ресурсу (практично не використовується)
• DELETE /books/(id)– видаляє дані із ідентифікатором (id).

Безпека та ідемпотентність

Дуже допоможуть у виборі HTTP методу знання безпеки та ідемпотентності цих методів.

Безпечний запит – це запит, який не змінює стан програми.

Ідемпотентний запит - це запит, ефект якого від багаторазового виконання дорівнює ефекту від одноразового виконання.

Судячи з даної таблиці, GET-запит ні змінювати стан ресурсу, якого застосовується. PUT та DELETE запити можуть змінювати стан ресурсу, але їх можна спокійно повторювати, якщо немає впевненості, що попередній запит виконався. У принципі, це логічно: якщо багаторазово повторювати запит видалення чи заміни певного ресурсу, результатом буде видалення чи заміна ресурсу. Але POST запит, як бачимо з таблиці, небезпечний і неідемпотентний. Тобто мало того, що він змінює стан ресурсу, так і багаторазове його повторення вироблятиме ефект, залежний від кількості повторень. Йому за змістом відповідає операція додавання нових елементів БД: виконали запит Х разів, і БД додалося Х елементів.

Також наведу приклад, чому GET-запити не повинні змінювати стан ресурсу. GET-запити можуть кешуватися, наприклад, на рівні проксі-сервера. У такому разі запит може навіть не дійти до сервера програми, а як відповідь проксі-сервер поверне інформацію з кешу.

HTTP коди

У стандарті HTTP описано понад 70 статусів кодів. Хорошим тоном є використання хоча б основних.

• 200 – OK – успішний запит. Якщо клієнт запросив будь-які дані, то вони знаходяться в заголовку та/або тілі повідомлення.
• 201 – OK – у результаті успішного виконання запиту було створено новий ресурс.
• 204 – OK – ресурс успішно вилучено.
• 304 – Not Modified – клієнт може використовувати дані з кешу.
• 400 – Bad Request – запит невалідний або не може бути опрацьований.
• 401 – Unauthorized – запит вимагає автентифікації користувача.
• 403 – Forbidden – сервер зрозумів запит, але відмовляється його обробити чи доступ заборонено.
• 404 – Not found – ресурс не знайдено.
• 500 – Internal Server Error – розробники API повинні намагатися уникнути таких помилок.

Ці помилки мають бути відловлені у глобальному catch-блоці, залоговані, але вони не повинні бути повернені у відповіді.

Чим більший набір кодів, який ми будемо використовувати, тим зрозумілішим буде API, який ми створюємо. Однак слід врахувати, що деякі коди браузери обробляють по-різному. Наприклад, деякі браузери отримавши код відповіді 307 відразу виконують редирект, а деякі дозволяють обробити таку ситуацію і скасувати дію. Перш ніж використовувати той чи інший код, необхідно повністю розуміти, як він оброблятиметься на клієнтській стороні!

Headers

• Content-Type- Формат запиту;
• Accept- Список форматів відповіді.

Параметри пошуку ресурсів

Щоб спростити використання сервісів, що відповідають за повернення будь-якої інформації, а також зробити їх найбільш продуктивними, необхідно використовувати як параметри запиту параметри для сортування, фільтрації, вибору полів і пагінації.

Фільтрування

Використовуйте унікальний параметр запиту для кожного поля для фільтрації. Це дозволить обмежити кількість інформації, що виводиться, що оптимізує час обробки запиту.

Наприклад, щоб вивести всі червоні книги, необхідно виконати запит:

GET /books?color=red

Сортування

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

GET /books?sort=-year,+name

Пагінація

Для того, щоб підтримати можливість завантаження списку ресурсів, які мають відображатися на певній сторінці програми, REST API повинен мати функціонал пагінації. Реалізується він за допомогою знайомих нам за SQL параметрами limit та offset. Наприклад:

GET /books?offset=10&limit=5

Крім того, хорошим тоном є виведення посилань на попередню, наступну, першу і останню сторінки в хідері Link. Наприклад:

Link: ; rel="next",
; rel="last",
; rel="first",
; rel="prev"

Вибір полів ресурсу

Для зручнішого використання сервісу, для економії трафіку можна надати можливість керувати форматом виведення даних. Реалізується наданням можливості вибору полів ресурсу, які має відновити REST сервіс. Наприклад, якщо необхідно отримати лише id книг та їх кольори, необхідно виконати наступний запит:

GET /books?fields=id,color

Зберігання стану

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

Приклад сервісу, що не зберігає стан:
Request1:
Request2: GET http://MyService/Persons/2 HTTP/1.1

Кожен із цих запитів може бути оброблений незалежно від іншого.

Приклад сервісу, що зберігає стан:
Request1: GET http://MyService/Persons/1 HTTP/1.1
Request2: GET http://MyService/NextPerson HTTP/1.1

Щоб обробити другий запит, серверу потрібно "запам'ятати" id останньої людини, яку запросили клієнта. Тобто. сервер повинен “запам'ятати” свій поточний стан, інакше другий запит може бути оброблений. При проектуванні сервісу, слід уникати потреби у зберіганні стану, оскільки це має низку переваг.

Переваги сервісу, що не зберігає стан:

• обслуговування обробляє запити незалежно друг від друга;
• архітектура сервісу спрощується;
• не потрібні додаткові зусилля для реалізації сервісів з використанням протоколу HTTP, який також не зберігає стану.

Недоліки сервісу, що не зберігає стан:

• клієнт сам повинен відповідати за передачу необхідного контексту сервісу.

Версійність

Хорошим тоном є підтримка версії REST API. Це дозволить надалі легко розширювати API без обов'язкового внесення змін до клієнтів, які вже користуються ним.
Є кілька підходів реалізації версійності:

• За допомогою Accept хидера. В даному випадку версія API вказується в Accept - Accept:text/v2+json
• З використанням URI. У такому підході версія API вказується прямо в URI - http://localhost/api/v2/books
• Використання кастомного хідера. Можна використовувати власний хидер, який відповідатиме лише за передачу версії API - API-Version:v2
• Використання параметра запиту. Можна використовувати параметр запиту передачі версії API - /books?v=2

Кожен із представлених способів має право на існування, у кожного є свої плюси та мінуси. Однак лише Вам вирішувати, який спосіб реалізації версійності підійде до Вашого проекту.

Документація

Для зручного користування нашими сервісами REST потрібно створити хорошу і зрозумілу документацію. Для цього можна використовувати різні інструменти, наприклад, Mashape або Apiary, але я рекомендую використовувати Swagger.

Swagger – це технологія, яка дозволяє документувати REST-сервіси. Swagger підтримує безліч мов програмування та фреймворків. Плюс Swagger надає UI для перегляду документації.

Отримати докладнішу інформацію про Swagger можна за цією .

Архівування

Кешування

Також для скорочення запитів до БД та збільшення швидкодії наших сервісів REST рекомендується застосувати механізм кешування. Кешування можна налаштовувати як на рівні сервера, так і в самому додатку залежно від ситуації.

Кешуванням можна керувати, використовуючи наступні HTTP заголовки:

• Date - дата та час створення ресурсу.
• Last Modified – дата та час останньої зміни ресурсу на сервері.
• Cache-Control - заголовок HTTP 1.1, який використовується для управління кешуванням.
• Age - час, що минув з моменту останнього отримання ресурсу, заголовок може бути доданий проміжним (між клієнтом та сервером) компонентом (наприклад, проксі-сервер)