×Закрыть

Ділимось лінками на ресурси чи просто порадами для найкращих практик створення RESTful API

Оскільки веб-розробка має тенденцію до переходу на
SPA, відповідно доля MVC-фреймворків плавно зменшується, REST-фреймворки потроху завойовують популярність.

Зараз цікавлюсь темою «найкращих практик створення RESTful API», поки що мої знання в цьому плані досить абстрактні.

Що я читав, та що мені здалось найбільш інформативним:
— from EN wiki: Representational state transfer
— from EN wiki: HATEOAS
— Everything About REST Web Services — What and How — Part 1, part 2

Але враховуючи досить абстрактний опис цієї архітектури, в сухому залишку «що запам’яталось» маю не так і багато:
— окрім звичних методів GET, POST, слід використовувати ще й PUT, DELETE та HEAD; стандартизація застосування цих методів спрощує розробку, бо різні розробники вже знають чого очікувати від такої архітектури;
— сервер із клієнтом повинні використовувати весь перелік стандартних кодів для HTTP, а не лише 200, 500 та 404;
— видаючи ресурси клієнту, сервер повинен давати контекстні лінки, призначені для управління цими ресурсами;
— для ресурсів краще передбачати версійність.


ERX = Employee Representation XML, ESRX = Employees Representation XML.

Ну це, взагалі-то, і все.

Щоб ви могли порадити до прочитання в інтернеті, чи можливо й самі спробуєте сформулювати «які саме особливості слід розуміти під поняттям REST-архітектури, RESTful API»?

LinkedIn
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Кто бы ещё поделился ссылками на реализацию Spring Security через REST.

По-моєму, досить сумнівна логіка у автора вживання «Кращий і найкращий»

Цілком чітка логіка. «Кращий» вживаємо, порівнюючи два об’єкти: «Краще мати хоча б Paint, ніж не мати жодного графічного редактора, хоча існують і кращі за нього редактори». «Найкращий» вживаємо, коли порівнюємо об’єкт з усіма іншими в групі об’єктів: «Найкращим з усіх описаних у тій статті редакторів я вважаю Photoshop, і він, звісно, кращий, ніж Paint».
pustunchik.ua/...cs/luchshiy-i-nailuchshiy
ua-mova.livejournal.com/1072920.html
ukrainskamova.com/..._tvorennja_jikh/6-1-0-101
тощо

Уговорили, дякую.

П.С. Щось гугл-хром підкреслює слово «уговорили», хіба теж невірно?

«Уговорити» може бути, чого ж (хоча я б надав перевагу іншому слову ;) ).

Пробую ближче підійти до практики створення RESTful API, для бекенда вибрав собі Restify (NodeJS-фреймворк).

Судячи із прикладів в документації, на скільки я зрозумів, при реалізації RESTful API ми по-суті автоматично приходимо до мікросервісів, тобто коли нам треба отримати певний додатковий ресурс (окрім того ресурса, який запитується із браузера користувача), ми використовуємо бекенд-клієнт і йдемо через HTTP, замість виклику напряму відповідних класів.

Виходить, що використання RESTful API — це один із інструментів роботи з мікросервісами. Мабуть мікросервіси стають мікросервісами, коли окрім RESTful API для них запроваждується, скажімо, механізм деплоя, який передбачає розгортання окремих сервісів... (хоча це щось я абстрактне сказав, але мабуть істина десь поруч)

Ніхто не в курсі, правильно я розумію це?

Мабуть мікросервіси стають мікросервісами, коли окрім RESTful API для них запроваждується, скажімо, механізм деплоя
Микросервисы — это изолированные части программы, поэтому как раз независимый деплой — это важное требование. РЕСТ интерфейс не является ни необходимым, ни тем более достаточным условием для того чтобы назвать что-то микросервисом.
Виходить, що використання RESTful API — це один із інструментів роботи з мікросервісами.
Нет, никакой это не инструмент. Это всего лишь стиль построение коммуникации между частями распределенной системы.
Так уж исторически сложилось что Web API (которое является упрощением RESTful API) — это простой и понятный способ построения коммуникации между частями системы. Поэтому “RESTful API” — это, наверное, самый популярный подход, но есть и другие (те же MQ вполне живой и легитимный подход, в некоторых ситуациях).
Нет, никакой это не инструмент. Это всего лишь стиль построение коммуникации между частями распределенной системы.
Мабуть «стиль комунікації» — це більше стосується абстрактної REST-архітектури, а не RESTful APIs, які вже реалізують цей стиль. Але це вже не суттєві деталі...

Підкажіть, пліз, можна сказати, що ключовою відмінністю між REST-архітектурою та MVC-архітектурою є цей самий «стиль комунікації»?

Конкретний приклад.
Скажімо, під час реєстрації користувача, коли він відправив свої дані, робочий потік приблизно наступний.

У фреймворку з MVC-архітектурою, ми у контролері:
1. підключаємо клас моделі, щоб перевірити чи ще немає такого email та username у нас у базі;
2. підключаємо клас валідації даних, щоб перевірити коректність введених даних;
3. підключаємо клас для роботи з поштою й відправляємо лист;
...

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

Так? Це є самою ключовою відмінністю?

П.С. Хм, виходить що у кожного сервіса повинен бути свій контролер. З іншого боку — сам контролер можна розглядати як окремий сервіс, а тому не всі сервіси зобов’язані мати свій контролер. Тобто, наприклад, усі публічні сервіси з контролерами, а всі «внутрішні» сервіси — без контролера.

Підкажіть, пліз, можна сказати, що ключовою відмінністю між REST-архітектурою та MVC-архітектурою є цей самий “стиль комунікації”?
Ой, тяжко (надо было подробнее расписывать).
.
1) Стиль коммуникации — это именно про коммуникацию, а не про архитектуру. Давайте заменим словосочитание “стиль коммуникации” на “использование ХТТП для связи между сервисами”. Это использование может быть на очень разных уровнях “модели зрелости” (см.
martinfowler.com/...hardsonMaturityModel.html )
.
2) РЕСТ и МВЦ не корректно сравнивать вообще, они предназначены совсем для разного и решают разные задачи.
РЕСТ про то как организовать распределенную систему (как передавать сообщения между модулями).
МВЦ про то как организовать обработку сообщения внутри одного модуля.

А із приводу контролерів... правильна в мене теорія?

API это часть проекта и а не нечто самостоятельное. Нельзя по каким то абстрактным критериям определить некую лучшую практику.
Это как спорить о том где ставить фигурную скобку на той же строке или на следующей.

ReSTful парадигма вообще очень зыбкий песок, так как RFC на него нет (в отличии от ReSTConf — RPC over ReST API). У всех абсолютно свое представление об этой технике построения web приложений. Самой веселой частью всего этого является вариация кодов ответа на запросы, уууууу, вот тут уже как кому кажется, каждый интерпретирует HTTP 1.0 ответы как ему вздумается, чаще всего возникают диллемы отностительно вот таких кодов: 400, 403 для невалидных операций.

Другой момент, как должен отвечать REST API сервер, если его спросили список объектов и не нашел их? Должен ли сервер ответить «Я нашел ничего, HTTP 200, content — {’objects’: []}» или сервер должен ответить «Я ничего не нашел, HTTP 404, content ’error: Not Found’ ».

Имея огромный опыт в разработке микросервисных платформ работающих по ReST API и ReSTconf, могу сказать — делайте как вам хочется, только напишите доку по API годную (свагер, руки, да что угодно).

Другой момент, как должен отвечать REST API сервер, если его спросили список объектов и не нашел их? Должен ли сервер ответить «Я нашел ничего, HTTP 200, content — {’objects’: []}» или сервер должен ответить «Я ничего не нашел, HTTP 404, content ’error: Not Found’ ».
Если вы на традиционном вебсайте выполняете поиск и не находите ничего — вы видите «нет результатов», а не 404 ошибку. В то же время если пытаетесь открыть страницу несуществующего объекта — 404.

Так же и в случае REST должно быть, имхо. Если запрашивается коллекция — должна вернуться пустая коллекция с кодом 200. Если запрашивается объект по id и такого объекта нет — ответ с кодом 404 и описанием ошибки (опционально).

Другой момент, как должен отвечать REST API сервер, если его спросили список объектов и не нашел их? Должен ли сервер ответить «Я нашел ничего, HTTP 200, content — {’objects’: []}» или сервер должен ответить «Я ничего не нашел, HTTP 404, content ’error: Not Found’ ».
Очень важный момент, который поможет вам ответить на ваш вопрос:
Ресурс != доменный объект.
Точно также как и объект != запись в БД.
Ресурс — это еще одна абстракция.

Пара полезных ресурсов для разработчиков API:
raml.org — большая махина, если подружиться с ней, то открывается много возможностей
jwt.io — удобный механизм аутентификации, в т.ч. и для API

Ого! Здавалося б скільки там тих принципів в REST, але по вашому лінку є навіть ось така немаленька специфікаія RAML 1.0

да. очень удобно. как на этапе проектирования АПИ, так и на этапе эксплуатации в продакшене.
* решает проблему консистентности АПИ и его документации
* позволяет разрабатывать потребителей АПИ параллельно с самим АПИ

Мы у нас на блоге писали об том, как настраивать REST API на проектах Symfony: www.grossum.com/blog/rest-api-symfony2-setting-it-up-in-minutes

Наскільки я знаю FOSRestBundle в стабільній версії не підтримує версійність... Використання форм мені здається якимось надлишковим... Як Ви будете валідувати дані наприклад при такому запросі:
LINK /images/my_dog.jpg HTTP/1.1
Host: example.org
Link: <http: example.com="" profiles="" joe="">; rel="tag"
Link: <http: example.com="" profiles="" sally="">; rel="tag"

або при будь-якому іншому де дані передаються в заголовках

Теж зараз реалізовую REST Api, про такі запроси як LINK/UNLINK теж варто памятати...

Ви маєте на увазі під LINK/UNLINK методи HTTP?

Небольшой сборник полезных шаблонов:
restcookbook.com

Справочник по проектированию АПИ:
jsonapi.org/format ( +моя прозрачная реализация объединений и фильтраций для любого существующего JSON API: github.com/alexeytokar/rainbow-rest )

Json Patch RFC:
tools.ietf.org/html/rfc6902

“RESTful Service Best Practices”
Лицензия: Creative Commons
Сайт: www.restapitutorial.com/lessons/whatisrest.html
Книга (2012 год): drive.google.com/...kakFsQ3c/view?usp=sharing
Инжой

священная книга (основная ценность не в содержании, а в священности) — www.ics.uci.edu/...pubs/dissertation/top.htm
для старта неплохо — shop.oreilly.com/product/9780596529260.do
немного самопиара — dou.ua/...a/digests/java-digest-20 + я почему-то думал что делал обзор ссылок про РЕСТ, но как оказалось что нет и надо будет таки сделать.
.
“/employee”, “/employees” — не делайте так, бо будет очень больно. Или __везде__ множественное число или __везде__ единственное.

окрім звичних методів GET, POST, слід використовувати ще й PUT та DELETE
Тут надо помнить что у ПУТа и ДЕЛЕТа, очень жесткий “контракт”, поэтому надо быть осторожным.
сервер із клієнтом повинні використовувати весь перелік стандартних кодів для HTTP, а не лише 200, 500 та 404
Никто никому ничего не должен. Идея РЕСТ в использовании протокола ХТТП по максимум (это не совсем корректное утверждение с теоретической точки зрения), но это не значит что надо использовать все и везде.
видаючи ресурси клієнту, сервер повинен давати контекстні лінки, призначені для управління цими ресурсами
Если вы про HATEOAS, то тут надо помнить что его использовании все еще не на самом высоком уровне: его используют далеко не все и довольно часто только в довольно простых сценариях.
.
РЕСТ — это архитектурный стиль (а не методология), поэтому, тут не может быть единственно правильного пути, могут быть только мнения.

По першому вашому лінку, виявляється навіть такі є автори:

DOCTOR OF PHILOSOPHY
in Information and Computer Science

А что с этим автором не так? Если вас смущает Doctor of Philosophy — это аналог нашего «кандидата наук», сокращенно — PhD.

Это и есть автор — единственный ... с его диссера все и началось :)

посмотрите книгу rest in practice

Ви про цю книгу говорите? Не опишете пару моментів, які вам з неї запам’ятались як особливість REST?

Шо за народ пошел. Все им сразу правильный ответ нужно выклянчить. А что через решение/чтение приходит понимание принципов — это слишком скучно.

Подписаться на комментарии