rest api что это простыми словами хабр
RESTful API — большая ложь
От переводчика:
Я впервые попробовал перевести статью такого объёма и IT-тематики, с радостью прочту ваши комментарии и замечания. Что же касается самой статьи: я не согласен с автором как минимум потому, что, по сути, он заменяет REST на… REST (. ), но немного в другом обрамлении. Однако, не смотря на то, что в статье преподносится много очевидных вещей, мне она показалась достойной обсуждения на Хабре.
Почему Вам стоит похоронить эту популярную технологию
RESTful api — это чудесно, ведь так?
Если за последние 10 лет Вы читали резюме веб-разработчиков, то Вам простительно думать, что RESTful API — это некое божественное дарование, сошедшее к нам с небес. REST API используется повсюду, даже маркетологи постоянно упоминают о нём в материалах, предназначенных сугубо для руководства или персонала.
Так на сколько всё же хороша идея REST API? Перед тем как мы разберемся с этим вопросом, давайте посмотрим откуда растут корни…
Откуда вообще взялся REST?
Данная технология стала популярной, когда она была подробно описана и представлена Роем Филдингом в его докторской диссертации под названием Architectural Styles and the Design of Network-based Software Architectures в 2000 году. Рой известен своими вкладами в развитие веба, в особенности HTTP.
Так что же такое RESTful API?
REST — это стиль архитектуры программного обеспечения для построения распределенных масштабируемых веб-сервисов. Рой выступал за использование стандартных HTTP методов так, чтобы придавать запросам определённый смысл.
Рой также утверждал, что HTTP-коды ответов помогут в определении смысла самих ответов. Существует около 38 кодов ответа и ниже вы можете увидеть их список. Названия некоторых я немного сократил для удобства:
Кстати, транзакция может быть более сложной и причины этому мы еще обсудим. Однако мы опустим те усложняющие факторы, которые связаны с сетями и кешированием, так как эти вопросы актуальны и для других технологий.
На самом деле RESTful API довольно ужасно
REST является отличным механизмом для многих вещей, например, таких как получение контента, и он отслужил нам верой и правдой почти 20 лет. Однако, настало время раскрыть глаза и признать, что концепция RESTful API является одной из худших идей, когда-либо существовавших в веб-разработке. Нет, я не спорю, Рой — отличный парень и, конечно же, у него было множество классных идей… Тем не менее, я не уверен, что RESTful API попадает в их список.
Вскоре мы посмотрим на другое, более правильное решение для построения API, но, перед тем как сделать это, нам следует понять 5 главных проблем RESTful API, которые делают его дорогим, уязвимым к ошибкам и неудобным. Начнём!
Проблема №1: До сих пор нет общего согласования того, что такое RESTful API
Вряд ли кто-то задумывался над тем почему эта технология называется именно «RESTful», а не «RESTpure»? (прим. переводчика: pure — чёткий, понятный) А потому что никто не может определиться с тем, что из себя представляют все методы запроса, коды ответа, тела и т.д.
Например, когда мы должны использовать код 200 ОК? Можем ли мы использовать его для подтверждения успешного апдейта записи, или нам стоит использовать код 201 Created? Судя по всему, нужно использовать код 250 Updated, однако его не существует. И еще, кто-нибудь может объяснить что означает код 417 Expectation failed?! Кто-нибудь кроме Роя, конечно.
Словарь HTTP методов и кодов слишком расплывчатый и неполный, чтобы прийти наконец к единым определениям. Нет никого, если я не ошибаюсь, кто нашел единый, общий порядок и призвал остальных его соблюдать. То, что подразумевается под 200 ОК в одной компании может обозначать вовсе иную информацию в другой, что делает обсуждаемую технологию непредсказуемой.
Если бы это было единственной проблемой, то я, наверное, смирился бы и продолжал писать RESTful API по сей день. Однако, наш список только раскрывается…
Проблема №2: Словарь REST поддерживается не полностью
Даже если бы мы решили первую проблему, то столкнулись бы со следующей, практической: большинство клиентских и серверных приложений поддерживают не все коды ответа и, собственно, глаголы, означающие HTTP-методы. Например, большинство браузеров имеют ограниченную поддержку PUT и DELETE.
Как же мы с этим справляемся? Одним из способов является вставка глагола, обозначающего нужный метод, в отправляемую форму. Это значит, что в данном случае запрос включает в себя:
Даже если мы всё же смогли бы согласовать всё вышеописанное, а еще магическим образом пофиксили всё подключённое к интернету, но не приспособленное к REST программное обеспечение — мы всё равно столкнёмся с очередной проблемой.
Проблема №3: Словарь REST недостаточно насыщен
Словарь, состоящий только из HTTP методов и кодов ответа, является слишком ограниченным для эффективной передачи и приёма разнообразной информации, необходимой всем приложениям. Представьте, что мы создали приложение, из которого мы хотим отправить клиенту ответ «render complete». К сожалению, мы не можем сделать это с помощью HTTP кодов, так как, во-первых, такого кода не существует, а во-вторых мы не можем его создать, так как HTTP — не расширяемый. Минутка разочарования. Думаю нам снова придётся вставлять то, что мы подразумеваем в тело ответа.
Также проблема в том, что у нас не один словарь, у нас их три! Коды ответов — это числовые значения (200, 201, 500), которые отличаются от представления методов запроса (GET, POST, PUT и т.д.), а тело ответа и вовсе в формате JSON. Выполнение REST транзакций — это как отправка письма на английском языке в Китай и получение оттуда ответа морзянкой. Все эти сложности являются крупным источником путаницы и ошибок. Вот мы и перешли к следующей глобальной проблеме: дебаггинг.
Проблема №4: RESTful API очень трудно дебажить
Если Вы когда-то работали с REST API, то Вы наверняка в курсе, что его почти невозможно дебажить. Для того, чтобы понять то, что происходит во время транзакции, нам приходится просматривать сразу 7 мест:
Проблема №5: Как правило, RESTful API привязаны к протоколу HTTP
RESTful API в дребезги разбивает один из фундаментальных законов о хорошей связи: содержимое сообщения должно быть абсолютно независимо от канала передачи. Их смешивание — это путь к сплошной путанице.
Постоянное переплетение HTTP протокола и передаваемой информации полностью лишает нас возможности переноса RESTful API на другие каналы связи. Портирование RESTfulAPI с HTTP на какой-либо другой протокол передачи данных требует полного распутывания и реструктуризации информации из семи разных точек, о которых мы говорили ранее.
К счастью, есть хорошее решение, которое позволяет избежать либо минимизировать все проблемы RESTful API. Встречайте!
Шаг вперёд: JSON-pure API
JSON-pure API справляется с большинством проблем, которые мы только что рассмотрели.
За последние десять лет меня не раз просили использовать RESTful вместо JSON-pure. Крайний раз, когда мне чуть было не пришлось поддерживать RESTful API, был в 2011 году. К моему счастью, бэк-енд команда согласилась параллельно с RESTful запустить JSON-pure API, просто перенеся все свои методы и коды в JSON.
Спустя несколько месяцев все мои знакомые, ранее использовавшие RESTful, перешли на JSON-pure, осознав, что это гораздо удобнее.
Архитектура REST
Введение
В русскоязычной части Интернета присутствует большое количество статей, посвященных веб-службам на основе SOAP и XML-RPC, но почему-то почти ничего нет про вполне заслуживающую внимания (но менее распространенную) архитектуру RESТ.
В данной статье описываются основы этой архитектуры, возможности и примеры её использования.
Что такое REST
REST (Representational state transfer) – это стиль архитектуры программного обеспечения для распределенных систем, таких как World Wide Web, который, как правило, используется для построения веб-служб. Термин REST был введен в 2000 году Роем Филдингом, одним из авторов HTTP-протокола. Системы, поддерживающие REST, называются RESTful-системами.
В общем случае 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) могут выполняться как со всеми 4-мя методами, так и только с помощью GET и POST.
Вот как это будет выглядеть на примере:
GET /book/ — получить список всех книг
GET /book/3/ — получить книгу номер 3
PUT /book/ — добавить книгу (данные в теле запроса)
POST /book/3 – изменить книгу (данные в теле запроса)
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-сервисов.
Как известно, web-сервис – это приложение работающее в World Wide Web и доступ к которому предоставляется по HTTP-протоколу, а обмен информации идет с помощью формата XML. Следовательно, формат данных передаваемых в теле запроса будет всегда XML.
Для каждой единицы информации (info) определяется 5 действий. А именно:
GET /info/ (Index) – получает список всех объектов. Как правило, это упрощенный список, т.е. содержащий только поля идентификатора и названия объекта, без остальных данных.
GET /info/ (View) – получает полную информацию о объекте.
PUT /info/ или POST /info/ (Create) – создает новый объект. Данные передаются в теле запроса без применения кодирования, даже urlencode. В PHP тело запроса может быть получено таким способом:
POST /info/ или PUT /info/ (Edit) – изменяет данные с идентификатором
DELETE /info/ (Delete) – удаляет данные с идентификатором
Еще раз отмечу, что в нашем примере /info/ — может и базироваться на какой-то другой информации, что может быть (и должно) быть отражено в URL:
/data/4/otherdata/6/info/3/ … и тому подобное.
Какие можно сделать из этого выводы:
Как видно, в архитектура REST очень проста в плане использования. По виду пришедшего запроса сразу можно определить, что он делает, не разбираясь в форматах (в отличие от SOAP, XML-RPC). Данные передаются без применения дополнительных слоев, поэтому REST считается менее ресурсоемким, поскольку не надо парсить запрос чтоб понять что он должен сделать и не надо переводить данные из одного формата в другой.
Практическое применение.
Самое главное достоинство сервисов в том, что с ними работать может какая угодно система, будь то сайт, flash, программа и др. так как методы парсинга XML и выполнения запросов HTTP присутствуют почти везде.
Архитектура REST позволяет серьезно упростить эту задачу. Конечно в реальности, того что описано не достаточно, ведь нельзя кому угодно давать возможность изменять информацию, то есть нужна еще авторизация и аутентификация. Но это достаточно просто разрешается при помощи различного типа сессий или просто HTTP Authentication.
Полноценный REST API для перфекционистов за 5 минут
Врачи говорят, что это взаимосвязано, мол перфекционизм — это стремление к совершенству, а простота позволяет подобраться к этому мифическому совершенству. Чем проще решение, тем меньше ошибок можно допустить, вот я и подсел. Я не стал с ними спорить и вместо того, что бы искать виновников моей истории, решил с этим жить и постараться повысить качество этой самой жизни.
Мир вокруг не идеален, сложную вещь сделать простой – невероятно сложно, поэтому всё чрезмерно усложнено. Людям нравится чувствовать себя профессионалами, поэтому они оперируют сложными терминами, когда в этом нет необходимости, так они ощущают свою значимость и заполняют пустоту, которая образовалась из-за страха потерянного времени.
Почему я должен постоянно вспоминать о том, общался я с этим человеком или нет? Мы уже перешли на ты? Я пишу какое-то коммерческое предложение и мне надо «Выкнуть» или это ответ на рядовое письмо и достаточно простого «вы». Почему мне постоянно надо расстраиваться, когда мне с порога совершенно незнакомый человек начинает «тыкать», как будто я его друг с курилки?
Я принципиально всем «выкаю» с маленькой буквы и я убеждён, что это имеет свою цену. Наверняка есть люди, которым не нравится, что их назвали с маленькой буквы и они не ответят на моё письмо.
Так зачем эти сложности?
Когда я упомянул про повышение качества жизни, я имел ввиду некоторые правила, которые помогают быстро принимать решения и не жалеть об этом. Например, я не использую сложные вещи постоянно, не общаюсь с людьми, которым нравится всё усложнять. Если вещь, которой вы пользуетесь каждый день – сложна, то это значит только то, что ей не уделили достаточно внимания. Если человек вам не может объяснить даже трудную для понимания тему простым языком, значит, он сам не до конца понимает о чём говорит.
Есть ещё кое-что, что имеет не менее важное значение – время. Время – бесценный ресурс, а выражение «Время — деньги» из уст умных людей вызывает у меня улыбку с разочарованием (выглядишь как идиот и чувствуешь себя так же). Я до сих пор не знаю ни одного миллиардера, которому деньги помогли прожить дольше других людей.
Введение
Речь пойдёт об инструменте, который позволит вам построить полноценный и простой в использовании REST API за минимальное количество времени. Называется он – Python Eve.
К сожалению в Интернете очень много инструкций на эту тему, но все они вводят в заблуждение. Начинающие разработчики, начитавшись подобных статей, думают, что REST API это GET/POST/PUT/DELETE. Заказчики думают, что это дело пары часов. А когда они встречаются вместе, происходят магия в виде Express.js/Mongoose/Passport и ещё кучи хлама, который течёт и временами блокирует event-loop. Всё это запускается с помощью какого-нибудь supervisor, потому что иногда падает и надо как-то перезапускать.
И всё бы ничего, но вчера у меня состоялся разговор с хабра-пользователем, который предложил воспользоваться «Express.js, MongoDB, Mongoose, Passport, отладчиком WebStorm’a и головой на плечах«. Похожие разговоры случались часто, поэтому я решил написать эту статью и «отсылать» ссылкой на неё.
Полноценный REST API?
Речь не только о реализации архитектурного стиля REST API, но и о протоколе HTTP, о валидации и кэшировании, о HATEOAS (wikipedia), о котором, похоже, вообще предпочитают не вспоминать. Затем нам понадобится фильтрация результатов и сортировка, постраничная навигация и частичное обновление записей. Потом мы задумаемся о целостности данных и условных запросах. Наверняка нам понадобится аутентификация, возможно захотим отображать данные не только в JSON, но и в XML. Это ещё про версионность и вложенные записи я не упомянул. Затем, как это обычно бывает, какой-то #$%$%^ начнёт долбить в наш могучий API с тяжёлым запросом и нам понадобится ограничить частоту запросов.
Даже если представить, что разработкой такого API займётся невероятно крутой разработчик с 3-мя мониторами, отладчиком WebStorm’a и головой на плечах, он затратит на это не просто много времени, а очень много. Поддержка кодовой базы будет обходиться дорого, а внедрение новых функций будет долгим.
Но мы с вами простоту – любим, а время – уважаем. Так приступим же!
Установка
Это обычный python-пакет, поэтому устанавливается он стандартным способом:
Если вас интересуют альтернативные методы установки, можете заглянуть в официальную документацию.
Быстрый старт
Перед тем, как мы начнём «творить» магию, нам понадобится база данных MongoDB. Если у вас её нет, вы можете воспользоваться любым бесплатным сервисом, например MongoLab. Регистрация займёт не больше минуты. После регистрации создайте базу данных и пользователя для этой базы.
Теперь давайте напишем минимальную версию нашего REST API. Для начала создадим главный файл run.py со следующим содержимым:
Теперь нам надо создать файл настроек settings.py:
На мой взгляд здесь всё достаточно просто и вопросов возникнуть не должно. Если это не так – добро пожаловать в комментарии. Полный список параметров конфигурации вы можете глянуть в документации.
Всё готово, запускаем:
Прелюдия
Вы уже подумали, что сейчас мы начнём безбожно «curlить», но я вынужден вас разочаровать. Мы, со свойственным нам перфекционизмом, воспользуемся инструментом автора, который обладает чувством прекрасного:
Инструмент называется HTTPie и ставится в один клик одну команду:
Игрища и забавы
HTTPie вызывается командой «http«. Для того, что бы отправить GET запрос к нашему API, выполним:
Благодаря HATEOAS мы видим, что у нас есть 2 ресурса: users и groups. Заглянем внутрь:
Давайте создадим пользователя johndoe:
Первое, на что стоит обратить внимание, это на нашу команду:
HTTPie увидел, что мы отправляем параметр username и превратил его в JSON:
Затем отправил нашему API методом POST. Давайте обратим внимание на ошибки:
Мы видим сразу весь список ошибок валидации и это здорово. Исправим их и выполним запрос повторно:
Ну вот, мы только что успешно создали нового пользователя. Давайте проверим так ли это:
Нет никаких сомнений, что это так. Настало время попробовать перезаписать (обратите внимание, не отредактировать, а перезаписать) пользователя. Делается это с помощью метода PUT, который надо указать явно (если не указать, будет выполнен POST):
Упс, ошибка. Я выше упоминал о целостности данных. Дело в том, что может произойти ситуация, в которой кто-то уже изменил запись, которую хотите поменять вы. И когда вы её отредактируете, то будете думать, что изменили одну запись, но на самом деле уже совсем другую.
Для того, что бы мы в такой ситуации не оказались, используется идентификатор ETag. В двух словах — это уникальный идентификатор, который генерируется Eve при каждом изменении записи. Используя этот идентификатор мы можем сказать нашему API, что хотим изменить запись только определённой версии и если она с тех пор была отредактирована, то наши изменения выполнены не будут. Делается это с помощью условного запроса с HTTP заголовком «If-Match«:
Обратите внимание каким образом мы передали HTTP заголовок HTTPie. Это не единственное, для чего может использоваться идентификатор ETag и условные запросы. Я здесь не буду останавливаться на этом, но советую вам ознакомиться с этой темой, если вы этого ещё не сделали.
Настало время создать новую группу. Для начала попробуем создать группу с несуществующим пользователем:
И действительно, пользователя с таким _id не существует. Обратите внимание как мы передаём список пользователей:
Подробнее вы можете почитать в официальной документации к HTTPie, которая такая же качественная, как и сам инструмент.
На этот раз мы укажем правильный _id:
«Усё добра», как говорила моя прабабушка. Проверим:
Прабабушка оказалась бы права. На этом можно было бы закончить, но мы поступим иначе.
Получим группу с пользователями, которые в неё входят, в развёрнутом виде:
Попросим тоже самое в XML:
Попробуем изменить только имя нашего пользователя (без полной перезаписи). Для этого воспользуемся HTTP методом PATCH:
Что сказала бы бабуля?
«Усё добра». Мне так понравилось, что я бы создавал пользователей пачками:
Найдём пользователя «John Doe» по его имени:
Отсортируем пользователей по их логину в обратном порядке:
Ну и наконец-то удалим всех пользователей:
Я бы не стал включать данную возможность в production. Указывается это в параметре RESOURCE_METHODS (стоит убрать из списка DELETE):
Заключение
Мы рассмотрели не все возможности Eve, но даже c учётом этого – получили законченный вариант REST API.
В данной статье я хотел обратить внимание на то, что настоящий RESTful сервис это гораздо больше, чем пара модулей для Node.js и в большинстве случаев нет необходимости разрабатывать такие вещи с нуля, а тем более писать статьи о том, как это сделать за один час. Достаточно взглянуть на историю развития проекта, что бы лишний раз убедиться в том, что пары часов/дней/недель недостаточно даже для хорошей команды.
Nicola Iarocci, автор Eve, создал прекрасный инструмент для быстрого развёртывания REST API, уделил этому достаточно внимания и сохранил простоту использования.
Как мы делали API для социальной сети (REST API для WEB)
Я в своей работе часто сталкиваюсь с разными новыми концепциями, идеологиями и проектами. В основном из-за того, что участвую в разработке разных больших проектов, в каждом из которых встречаю что-то новое. Сегодня я хочу рассказать о своем опыте с REST API. Идеологии, которую мне как-то раз довелось применить при разработке одной социальной сети.
Об этом уже немало написано, и все же чего-то полного, позволяющего найти все необходимые мне детали в одном месте, когда я только начинал этим заниматься, в русскоязычной редакции я не встречал. Попробую собрать то, что удалось выяснить, путем проб, ошибок и постоянных поисков в работе с различными проектами. Итак, приступим!
Хочу сразу оговориться: REST для меня — это, в первую очередь, идеология, к которой я отношусь трепетно и нежно. И, если кто-то не готов принять ее такой, какая она есть — не стоит читать дальше эту статью. У программиста всегда есть куча полезных дел, которыми можно заняться, пока приходит понимание необходимости писать узнаваемые интерфейсы и прятать за их простотой логику приложений любой сложности…
Сразу должен оговорить, что я программист, а не писатель и это моя первая статья. Возможно, получилось сухо, но мы тут все технари, надеюсь, будет интересно. В статье я буду описывать свой опыт с REST API. Постараюсь сделать статью универсальной, чтобы эту идеологию по моей статье можно было применять для любого интернет-проекта.
Теперь давайте по порядку.
REST (Representational State Transfer — репрезентативная передача состояния).
Рой Филдинг — описал подход, названный REST, еще в 2000 году, этот подход лег в основу всем известного протокола HTTP. Можно встретить две разновидности написания для этого архитектурного стиля программирования: REST и RESTful, отличия в значениях этих терминов нет, просто RESTful это прилагательное от REST, т. е. RESTful API — это API, отвечающее принципам REST (Прошу прощения у тех, кто знал, но такие вопросы задают достаточно часто).
REST (Representational State Transfer — репрезентативная передача состояния).
Структура REST API
1. Клиент-серверная архитектура
2. Stateless сервер
4. Многослойная структура
5. Единый интерфейс
Теперь о каждом элементе поподробней.
Архитектура, клиент— сервер. Отделяем логику приложения от различных клиентов, делаем их код более переносимым, а структуру сервера более простой и масштабируемой. Разработка клиентов и сервера может вестись совершенно независимо.
Stateless — сервер. Состояние клиента не хранится на сервере, ни в каком виде, этим занимается исключительно сам клиент. Это упрощает доработку и сопровождение сервера, делает его более стабильным.
Кешируемость. Должна быть разработана четкая система кеширования запросов к серверу, что позволяет значительно улучшить производительность.
Многослойная структура. Наличие/отсутствие промежуточных серверов кеширования, балансировки нагрузки, дополнительного проксирования должно оставаться совершенно незамеченным со стороны клиентов.
Идентификация ресурсов. Каждый ресурс обладает уникальным идентификатором URI (Uniform Resource Identifier — универсальный идентификатор ресурса). Например:
Что касается ID, советую посмотреть в сторону UUID (universally-unique identifier), его поддерживает большинство баз данных и такой подход поможет обеспечить кросc-системную уникальность идентификаторов. Пример:
Взаимодействие с ресурсами через представления. Каждый ресурс имеет свой уникальный адрес URI (представление), и несколько глаголов для управления этим представлением.
Самодостаточные сообщения. Каждый ответ должен содержать всю необходимую информацию, чтобы его можно было правильно обработать, не обращаясь к помощи других ресурсов.
HATEOAS. Hypermedia As The Engine Of Application State.
Гипермедиа в качестве механизма управления состояниями приложения.
Слова — Representational State Transfer должны вызывать в голове появление картинки работы грамотного веб приложения: сеть из веб-страниц (назовем их состояниями), в которой пользователь перемещается кликая по ссылкам (смена состояний) для перехода на следующую страницу (представляющую собой очередное состояние приложения).
Рой Филдинг
Ключ к пониманию HATEOAS удивительно прост — в каждом полученном ответе содержится ссылка на следующий запрос.
Гипермедиа — это тип содержимого ресурса с включенной гипертекстовой разметкой. Гипертекст в данном контексте, как считает сам Филдинг, это одновременное представление информации и элементов выбора.
Таким образом, гипермедиа это просто расширение, для которого характерно наличие в информационном содержимом временных ссылок на другое содержимое внутри медиа потока.
Код по требованию. Опциональный элемент структуры. Позволяет получать программный код для последующего его исполнения на клиенте.
Таким образом, если ваше приложение отвечает всем требованиям (ограничениям), описанным выше, оно смело может называться RESTful. Исключение представляет лишь код по требованию — этот параметр опционален.
Хороший API просто понять и легко применять.
Основы REST через HTTP.
Ресурс — уникальный объект, доступный по уникальному URL.
Основные URL должны быть понятны без документации.
Для начала, желательно все URL адреса вашего API начинать с префикса, например:
это поможет упростить сопровождение API в будущем. Хорошим вариантом может оказаться префикс в имени домена:
Существует 2 основных типа ресурса в архитектуре REST: коллекция и элемент коллекции.
Коллекция представляет собой набор самостоятельных и самодостаточных элементов.
Пример ссылки на коллекцию пользователей:
Элемент коллекции пользователей, или конкретный пользователь, в таком случае, может быть представлен в виде:
Существительные — хорошо, глаголы — плохо.
Имена коллекций должны представлять сущности (существительные во множественном числе), и они должны быть максимально конкретными и понятными (самодокументирующимися). Если речь идет о собаках, то это должны быть собаки, а не просто животные.
Каждым ресурсом в RESTful API управляет несколько определенных минимально необходимых глаголов. Для большинства случаев достаточно 4 основных глагола (HTTP метода):
GET, PUT, DELETE — идемпотентны.
Идемпотентность означает, что сколько бы раз мы не вызывали такой метод — результат будет один и тот же.
| Ресурс | POST | GET | PUT | DELETE |
|---|---|---|---|---|
| /users | Создать пользователя | Показать список всех пользователей | Обновить список всех пользователей | Удалить всех пользователей |
| /users/ae25b8 | Ошибка | Показать Василия Пупкина | Если есть, обновить Пупкина, если нет Ошибка | Удалить Василия Пупкина |
Связи.
Если необходимо показать иерархическую связь между объектами, делаем так.
Коллекция машин пользователя:
Не стоит писать длинные адреса — это плохо:
Такие адреса нелегко читать и искать в документации, часто это вообще не имеет смысла — идентификаторы уникальные и «/cars/c7b45e» абсолютно однозначно относится к «/users/ae43bc». Данный вариант следует сократить:
Ошибки.
Следует различать 2 основных семейства статус кодов (HTTP Status Code):
4xx — проблема возникла на стороне пользователя и он сам может ее исправить, правильно введя необходимую для запроса информацию.
5xx — проблема возникла на сервере и для ее решения пользователь может отправить запрос к службе поддержки.
Ошибки должны быть четко описаны, чтобы не только пользователь знал, что ему необходимо сделать, но и вы легко ориентировались, если пользователь присылает вам запрос для решения проблемы.
Пример хорошо написанного ответа на ошибку:
HTTP Status Code: 401
Помните! Вы пишете API для таких же разработчиков как и Вы.
Используйте необходимый минимум статус кодов в приложении.
Иногда может быть достаточно 3:
В некоторых случаях полезно иметь параметр для подавления статус кода ошибки, что бы клиент всегда, при необходимости, мог получить код 200, например.
Это добавит нелишней гибкости Вашему API.
Версионность.
Обязательно указывайте номер версии, даже если не планируете изменение интерфейса — все может быстро измениться.
Версию можно указать в строке адреса:
или в параметрах запроса:
Нет смысла делать длинными названия версий, вставлять в них точки: v1.03
Версии интерфейса должны меняться максимально редко, в то время как внутреннюю логику работы API можно менять, как только появилась необходимость. В реальности настоящая версия API может быть, например, v2.034-beta2, но версия интерфейса, и, соответственно, представленная в адресе версия будет просто 2.
Постраничная выдача.
Любая коллекция, какой бы маленькой, по Вашему мнению, она не была должна отдаваться постранично. Определитесь с форматом выдачи коллекции, например, Content-Type: application/json <«data»:<>, «paging»: <«limit»: 50, «offset»: 0, «total»: 150>> старайтесь всегда использовать одинаковый формат во всех ответах приложения — облегчите жизнь и себе и разработчикам клиентского ПО.
Стоит выбрать какие-то дефолнные значения для параметров «limit», «offset», и, скорее всего, ограничивать максимальное значение для «limit».
Прячьте все сложные компоненты запроса за «?».
Если в Вашем GET запросе необходимо использовать различные фильтры — поместите их за знаком вопроса (в параметрах URL):
Отдавайте пользователю только то, что он хочет.
Позвольте клиенту получать только те поля в запросе, которые ему нужны:
Формат отдаваемых данных.
Не ограничивайтесь каким-то одним форматом. Сделайте опционально несколько, например, json и xml. Таким легким способом можно значительно упростить разработку для клиентов, и отпадет необходимость выбора чего-то одного. Формат возвращаемых данных можно описывать как в HTTP заголовках, так и в строке запроса:
И обязательно стоит выбрать какой-то формат по умолчанию.
Поиск.
Это один из немногих видов ресурса, которому суждено остаться глаголом. Имею в виду глобальный поиск.
Опять же в зависимости от системы используемого поискового движка можно применять различные фильтры.
Какой-то локальный поиск, в пределах коллекции, можно осуществить и простыми фильтрами:
Авторизация.
Используйте, по возможности, последнюю версию OAuth — OAuth 2.0 — эта система хорошо известна разработчикам, и хорошо себя зарекомендовала. Зачем выдумывать велосипед?
Документация.
Это один из самых важных аспектов хорошего API. Любой, кто, когда-либо сталкивался с написанием клиентских скриптов, со мной согласится. Часы, потраченные на хорошую документацию, с лихвой окупятся долгими месяцами работы службы поддержки. Фокус прост — опишите сжато и четко все получаемые и отдаваемые данные, а также назначение методов. Помните! Вы пишете для программистов. Не стоит описывать какие-то очевидные моменты. Приведите все отдаваемые статус коды; перечислите все принимаемые параметры опишите их, где необходимо; давайте ссылки на более подробный материал; приводите примеры получаемых данных, если это уместно, с их описанием.
Ссылки.
Старайтесь отдавать в ответах ссылки на все связанные ресурсы, если хотите соответствовать принципу HATEOAS, и называться RESTful. За это Вас будут очень любить разработчики клиентских программ — им не придется самим генерировать эти ссылки.
Теперь самое главное!
Фасад Паттерн для API.
Разработку любого API следует начинать с детальной проработки интерфейса. Фактически к началу написания кода на руках должны быть все URI Вашего API с подробной документацией всех параметров каждого доступного для данного URI метода, со всеми возвращаемыми статус кодами и форматами возвращаемых данных. В идеале, этот интерфейс уже не должен меняться в ходе дальнейшей разработки. Такой подход в значительной степени облегчает и ускоряет работу над основным кодом API, и позволяет параллельно писать клиентское ПО уже на самых начальных этапах разработки.
Помните! Интерфейс API должен быть максимально простым и понятным, только так можно достичь счастья и гармонии.
Пару слов в заключение
В результате мы с командой успешно сделали социальную сеть, в которой применили REST API. Сеть, к слову, была на PHP, в частности Symfony2, хотя этот подход применим и на других технологиях. Надеюсь, моя первая статья была Вам интересна. Буду рад услышать вопросы и мнения в комментариях.
Приглашаю на курсы по веб-разработке от бизнес-школы Digitov, которые веду Я: Хочу стать Junior PHP Developer! (для новичков), Symfony 2. Гибкая разработка (для специалистов), а также, которые ведут мои коллеги: Разработка веб-приложений на Python / Django (для новичков) и Ruby on Rails. По рельсам к профессиональной разработке (для новичков). Подписывайтесь на курсы сейчас и сможете купить их со скидкой
P.S. Чтобы получать наши новые статьи раньше других или просто не пропустить новые публикации — подписывайтесь на фан страницы SECL Group: Facebook, VK, и Twitter
Автор: Сергей Харланчук, Senior PHP Developer / Team Lead, компания «SECL GROUP» / «Internet Sales Technologies»