Тепер давайте по порядку.
REST (Representational State Transfer - репрезентативна передача стану).
REST (Representational State Transfer - репрезентативна передача стану).
Структура REST API
1. Клієнт-серверна архітектура
2. Stateless сервер
4. Багатошарова структура
5. Єдиний інтерфейс
- ідентифікація ресурсів
- Взаємодія з ресурсами через уявлення
- самодостатні повідомлення
- Гіпермедіа як механізм управління станами додатки (HATEOAS)
6. Код на вимогу (опціонально)
Тепер про кожен елемент більш детально.
Архітектура, клієнт - сервер. Відокремлюємо логіку додатки від різних клієнтів, робимо їх код більш стерпним, а структуру сервера простіший і масштабованої. Розробка клієнтів і сервера може вестися абсолютно незалежно.
Stateless - сервер. Стан клієнта не зберігається на сервері, ні в якому вигляді, цим займається виключно сам клієнт. Це спрощує доопрацювання і супровід сервера, робить його більш стабільним.
Кешіруемость. Повинна бути розроблена чітка система кешування запитів до сервера, що дозволяє значно поліпшити продуктивність.
Багатошарова структура. Наявність / відсутність проміжних серверів кешування, балансування навантаження, додаткового проксінг має залишатися абсолютно непоміченим з боку клієнтів.
Ідентифікація ресурсів. Кожен ресурс має унікальний ідентифікатор URI (Uniform Resource Identifier - універсальний ідентифікатор ресурсу). наприклад:
Що стосується ID, раджу подивитися в сторону UUID (universally-unique identifier), його підтримує більшість баз даних і такий підхід допоможе забезпечити кросc-системну унікальність ідентифікаторів. приклад:
Самодостатні повідомлення. Кожна відповідь має містити всю необхідну інформацію, щоб його можна було правильно обробити, не звертаючись до допомоги інших ресурсів.
HATEOAS. Hypermedia As The Engine Of Application State.
Гіпермедіа як механізм управління станами додатки.
Гіпермедіа - це тип вмісту ресурсу з увімкненою гіпертекстової розміткою. Гіпертекст в даному контексті, як вважає сам Філдінг, це одночасне подання інформації та елементів вибору.
«Таким чином, гіпермедіа це просто розширення, для якого характерна наявність в інформаційному вмісті тимчасових посилань на інший вміст всередині медіа потоку».
Код на вимогу. Опціональний елемент структури. Дозволяє отримувати програмний код для подальшого його виконання на клієнті.
Таким чином, якщо ваш додаток відповідає всім вимогам (обмеженням), описаним вище, воно сміливо може називатися RESTful. Виняток становить лише код на вимогу - цей параметр опціональний.
Хороший API просто зрозуміти і легко застосовувати.
Основи REST через HTTP.
Ресурс - унікальний об'єкт, доступний за унікальним URL.
Основні URL повинні бути зрозумілі без документації.
це допоможе спростити супровід API в майбутньому. Хорошим варіантом може виявитися префікс в імені домена:
Існує 2 основних типи ресурсу в архітектурі REST: колекція і елемент колекції.
Колекція представляє собою набір самостійних і самодостатніх елементів.
Приклад посилання на колекцію користувачів:
Елемент колекції користувачів, або конкретний користувач, в такому випадку, може бути представлений у вигляді:
Іменники - добре, дієслова - погано.
Імена колекцій повинні представляти сутності (іменники у множині), і вони повинні бути максимально конкретними і зрозумілими (самодокументірующіміся). Якщо мова йде про собак, то це повинні бути собаки, а не просто тварини.
Кожним ресурсом в RESTful API управляє кілька певних мінімально необхідних дієслів. Для більшості випадків достатньо 4 основних дієслова (HTTP методу):
GET, PUT, DELETE - ідемпотентна.
Ідемпотентність означає, що скільки б разів ми не викликали такий метод - результат буде один і той же.
Колекція машин користувача:
Слід розрізняти 2 основних сімейства статус кодів (HTTP Status Code):
4xx - проблема виникла на стороні користувача і він сам може її виправити, правильно ввівши необхідну для запиту інформацію.
5xx - проблема виникла на сервері і для її вирішення користувач може відправити запит до служби підтримки.
Помилки повинні бути чітко описані, щоб не тільки користувач знав, що йому необхідно зробити, але і ви легко орієнтувалися, якщо користувач надсилає вам запит для вирішення проблеми.
Приклад добре написаного відповіді на помилку:
HTTP Status Code: 401
Пам'ятайте! Ви пишете API для таких же розробників як і Ви.
Використовуйте необхідний мінімум статус кодів в додатку.
Іноді може бути досить 3:
2. 400 Bad Request (некоректний запит)
3. 500 Internal Server Error (внутрішня помилка сервера)
Якщо мало, доповнюйте в міру необхідності:
1. 201 Created (успішно створений)
2. 304 Not Modified (дані не змінилися)
3. 404 Not Found (не знайдене)
5. 403 Forbidden (доступ заборонений)
Намагайтеся оцінити користь від кожного доданого Вами елемента для користувача. Пам'ятайте, що велика кількість, особливо непотрібних елементів, здатне заплутати навіть досвідчених розробників.
У деяких випадках корисно мати параметр для придушення статус коду помилки, що б клієнт завжди, при необхідності, міг отримати код 200, наприклад.
Це додасть не зайвою гнучкості Вашому API.
Версійність.
Обов'язково вказуйте номер версії, навіть якщо не плануєте зміна інтерфейсу - все може швидко змінитися.
або в параметрах запиту:
Немає сенсу робити довгими назви версій, вставляти в них точки: v1.03
Посторінкова видача.
Будь-яка колекція, якою б маленькою, на Вашу думку, вона не була винна віддаватися посторінково. Визначтеся з форматом видачі колекції, наприклад, Content-Type: application / json, «paging»:> намагайтеся завжди використовувати однаковий формат у всіх відповідях додатки - полегшите життя і собі і розробникам клієнтського ПЗ.
Варто вибрати якісь дефолнние значення для параметрів «limit», «offset», і, швидше за все, обмежувати максимальне значення для «limit».
Ховайте всі складні компоненти запиту за «?».
Якщо у Вашому GET запиті необхідно використовувати різні фільтри - помістіть їх за знаком питання (в параметрах URL):
Віддавайте користувачеві тільки те, що він хоче.
Дозвольте клієнту отримувати тільки ті поля в запиті, які йому потрібні:
Формат віддаються даних.
Не обмежуйтеся якимось одним форматом. Зробіть опціонально кілька, наприклад, json і xml. Таким легким способом можна значно спростити розробку для клієнтів, і відпаде необхідність вибору чогось одного. Формат повертаються даних можна описувати як в HTTP заголовках, так і в рядку запиту:
І обов'язково варто вибрати якийсь формат за замовчуванням.
Це один з небагатьох видів ресурсу, якому судилося залишитися дієсловом. Маю на увазі глобальний пошук.
Знову ж таки в залежності від системи використовуваного пошукового движка можна застосовувати різні фільтри.
Якийсь локальний пошук, в межах колекції, можна здійснити і простими фільтрами:
Використовуйте, по можливості, останню версію OAuth - OAuth 2.0 - ця система добре відома розробникам, і добре себе зарекомендувала. Навіщо вигадувати велосипед?
Документація.
Це один з найважливіших аспектів хорошого API. Той, хто, коли-небудь стикався з написанням клієнтських скриптів, зі мною погодиться. Годинники, витрачені на хорошу документацію, з лишком окупляться довгими місяцями роботи служби підтримки. Фокус простий - опишіть стисло і чітко все одержувані і віддаються дані, а також призначення методів. Пам'ятайте! Ви пишете для програмістів. Не варто описувати якісь очевидні моменти. Наведіть всі віддаються статус коди; перерахуйте всі прийняті параметри опишіть їх, де необхідно; давайте посилання на більш детальний матеріал; приводите приклади одержуваних даних, якщо це доречно, з їх описом.
Намагайтеся віддавати у відповідях посилання на всі пов'язані ресурси, якщо хочете відповідати принципу HATEOAS, і називатися RESTful. За це Вас будуть дуже любити розробники клієнтських програм - їм не доведеться самим генерувати ці посилання.
Тепер найголовніше!
Фасад патерн для API.
Розробку будь-якого API слід починати з детального опрацювання інтерфейсу. Фактично до початку написання коду на руках повинні бути всі URI Вашого API з докладною документацією всіх параметрів кожного доступного для даного URI методу, з усіма повертаються статус кодами і форматами повертаються даних. В ідеалі, цей інтерфейс уже не повинен змінюватися в ході подальшої розробки. Такий підхід в значній мірі полегшує і прискорює роботу над основним кодом API, і дозволяє паралельно писати клієнтське ПЗ вже на початкових етапах розробки.
Пам'ятайте! Інтерфейс API повинен бути максимально простим і зрозумілим, тільки так можна досягти щастя і гармонії.
Senior Web Developer / Team Lead, компанія SECL Group / Internet Sales Technologies