что такое рест в вирте

Как спроектировать правильный конечный автомат на REST

Разработчики часто неверно понимают концепцию передачи состояния представления (REST). Большинство ошибок связаны с трактовкой архитектурного ограничения HATEOAS. В этой статье мы разберем популярные заблуждения, связанные с REST, и подробно остановимся на HATEOAS. В конце текста на примере имитации конечного автомата — кухонного тостера — рассмотрим, как гипермедиа может использоваться в REST API для управления состояниями.

Примечание: Это адаптированный перевод статьи Designing a True REST State Machine Билла Доррфельда, технического журналиста и специалиста по API. Повествование ведётся от лица автора оригинала.

История REST и гипермедиа

Концепция гипермедиа сформировалась в 1941 году, когда аргентинский писатель Хорхе Луис Борхес написал «Сад расходящихся тропок» — рассказ, в котором страницы текста ссылаются друг на друга. Вероятно, это первый в истории пример гипертекста (на самом деле впервые гипертекст использовался в романе Джеймса Джойса «Улисс», — прим. редакции). Сейчас в массовой культуре есть множество примеров реляционных связей — от сюжета видеоигры Bioshock до серии детских романов-ужасов Роберта Стайна Goosebumps, — но во времена Борхеса такой прием был беспрецедентным.

Гипермедиа — система организации информации, элементы которой взаимосвязаны и, кроме самого гипертекста, включают в себя видео, картинки, аудио и другие типы контента.

Прокачивайте свой уровень программирования: На Хекслете есть несколько десятков треков — специальных курсов для опытных программистов, позволяющие повысить уровень компетентности разработчика в разных направлениях.

Затем произошло несколько событий, которые помогли REST сформироваться в концепцию с четкой структурой:

Что такое REST

Все технические аспекты, которые определяют REST, трудно раскрыть в виде статьи в блоге — это слишком объемная тема. Поэтому предлагаю пойти от обратного: рассмотреть четыре распространенных заблуждения — они помогут нам понять, чем REST точно не является.

Заблуждение №1: REST — это просто CRUD

CRUD — акроним, который обозначает четыре базовые функции при работе с персистентными хранилищами данных: «создание, чтение, редактирование, удаление». CRUD соответствует действиям в SQL, но он плохо соотносится с методами HTTP.

Хотя GET и DELETE в REST и CRUD совпадают, POST, PUT и PATCH отвечают за разные операции. Например, в REST POST означает не только «создать» — это универсальный метод. С его помощью туннелируется весь протокол SOAP при использовании с HTTP.

Поскольку HTTP-методы не соответствуют CRUD, теоретик и популяризатор REST Асбьёрн Ульсберг утверждает, что создатели различных API должны подумать, как они могут описывать API иным способом: «Не ограничивайте себя CRUD при разработке REST API. Прочитайте спецификацию и поймите семантику каждого метода, а затем правильно используйте ее».

Если перефразировать, смысл этой цитаты сводится к тому, что REST — это стиль архитектуры, а не протокол. Таким образом, ошибочно называть «RESTful» HTTP API с операциями CRUD.

Заблуждение №2: некоторые конструкции URI «более RESTful», чем другие

Унифицированные идентификаторы ресурсов (URI) — основа концепции REST. Они позволяют определять ресурсы и действия с ними. Однако многие разработчики ошибочно считают, что могут отличить качество построения REST API просто на основе того, как структурирован URI. Проведем эксперимент: сможете ли вы сказать, какой URI «более RESTful»?

Тот факт, что мы указали URI, метод и описание для каждого вызова API, еще не значит, что мы создали REST API — мы просто задокументировали наши URI, как если бы мы задокументировали операции удаленного вызова процедур (RPC). Ульсберг отмечал, что такой подход усложняет работу и лишает сервис гибкости.

Заблуждение №3: API-интерфейсам REST нужны версии

Представим, что у нас есть таблица базы данных под названием «Referer». После нескольких лет использования мы заметили, что имя базы написано с ошибкой и решили изменить его на «Referrer». Клиенты уже взаимодействуют со старым именем таблицы в своих SQL-операторах, поэтому обновить имя базы будет крайне сложно — прежде придется обновить все клиенты.

Читайте также: Как устроен функциональный диалект Лиспа Clojure и почему использующие его программисты восхищаются им

То же самое с API: если мы решим обновить один из /blogposts/ в URI из примеров, указанных выше, обновления потребуют все клиенты. Это приведет к созданию второй версии — то есть к необходимости обновить документацию и все клиенты. Резюмируя, можно сказать, что строго запрограммированное управление версиями в URI — это боль.

Заблуждение №4. Гипермедиа необязательна для REST API

В интервью Майку Амудсену в 2014 году Филдинг сказал следующее: «Гипермедиа как механизм управления состоянием приложения — это ограничение REST. Это не одна из опций и не идеал, к которому нужно стремиться. Гипермедиа — это данность и ограничение. Вы либо принимаете их, либо не занимаетесь REST».

REST состоит из 6 основных ограничений — так называемых ограничений Филдинга. Он выглядит так:

При этом последний пункт — «Единообразие интерфейса» — состоит из еще нескольких подпунктов:

Среди них HATEOAS, вероятно, самое важное и уникальное, но наименее понятное условия REST.

По сути, HATEOAS или гипермедиа как механизм управления состоянием, — это подход к описанию ресурсов API. С его помощью можно установить инверсию контроля за ресурсами, которые клиент может вызвать, вместо того, чтобы просто перечислять каждый из них и указывать список функций, которые можно с ними выполнить. Именно благодаря этому сервер может отвечать за состояние ресурса.

Чтобы лучше понять эту идею, Ульсберг советует воспользоваться методом, предложенным Дональдом Норманом в книге «Дизайн повседневных вещей». Так же, как чашка сделана для того, чтобы ее взяли за ручку и подняли, а кнопка — чтобы быть нажатой, гипермедиа хочет сообщить вам, что делать с тем или иным ресурсом. Гипермедиа — это ссылки и метаданные для операций, которые помогают разработчикам или машинам выполнять дополнительные действия.

Асбьёрн Ульсберг описывает гипермедиа так: «Если вы посмотрите на гипермедиа как на рецепт того, как должен выглядеть следующий запрос, вы поймете, что такое гипермедиа».

Пример конечного автомата: IoT-тостер

Разберем концепцию гипермедиа как механизма состояния приложения на примере простого конечного автомата — тостера, подключенного к интернету вещей (IoT), которым можно управлять через интернет.

Конечный автомат — это абстрактная модель, которая содержит конечное количество состояний чего-либо. В нашем случае тостер запускается после включения — переходит в состояние нагрева. Затем он достигает верхнего предела температуры и переходит в состояние ожидания, снижая температуру. Этот цикл продолжается до тех пор, пока кусок хлеба не поджарится достаточно хорошо — после этого тостер отключается.

Как управлять тостером с помощью REST и гипермедиа? Филдинг писал, что каждая страница в сети представляет собой отдельное состояние одного ресурса, которое можно получить с помощью вызова GET (этот процесс показан в таблице выше). То есть вы можете получить какие-либо данные с помощью идентификатора в URI.

Попробуем сделать это: для начала вызовем наш тостер с помощью GET:

Ответ будет выглядеть примерно так:

В ответе содержится идентификатор, который показывает, с каким ресурсом мы работаем. Следом отображается текущее состояние ресурса, а ниже — список возможных операций, которые с ним можно совершить.

Теперь попробуем изменить состояние тостера. Для этого отправим HTTP-запрос PUT:

Ответ будет выглядеть примерно так:

Хорошо, теперь мы включили тостер. Однако в ответе видно, что его мощность по-прежнему на нуле — он все еще не нагревается. Попробуем вызвать изменение мощности:

Мы увеличили мощность — теперь в ответе видно, что тостер нагревается.

Теперь мы можем перевести тостер в режим ожидания и снова увеличить мощность. Однако вместо этого отправим еще один вызов GET на идентификатор устройства:

С момента нашего последнего запроса тостер перешел в состояние ожидания. В ответе видно, что мы все еще можем отключить его или отрегулировать температуру, усилив мощность нагрева.

Если подождать еще несколько минут, следующий запрос к конечному автомату, скорее всего, приведет его к состоянию «выключение» или «выключено» — то есть в то состояние, с которого мы начинали.

Заключение

Сеть функционирует как набор идей, связанных друг с другом гипертекстом. Ульсберг считает, что веб-API должны имитировать этот принцип, а важным аспектом в реализации API является гипермедиа. Для тех, кто только начинает работать с REST, создание HATEOAS-совместимого API — это огромный шаг вперед по сравнению с API-интерфейсами в стиле RPC.

«Если вы используете гипермедиа, вы можете добавлять отношения, ссылки и операции к ресурсам, не нарушая работу существующих клиентов, и наделяя новых клиентов новыми функциями», — писал Ульсберг.

Такой подход подразумевает переосмысление традиционного подхода к управлению версиями. Мнения Ульсберга и Филдинга в этом вопросе сходятся: управление версиями в REST — плохая идея. Когда вы в последний раз видели номер версии на веб-сайте? HTML не требует контроля версий, и JSON тоже в нем не нуждается.

Уделяя больше внимания ресурсам как конечному автомату, мы можем сообщать потребителям текущее состояние, с помощью которого мы совершаем операции. Такой подход снижает степень связанности и в бизнес-доменах, где состояние приложения состоит из множества сложных и взаимозависимых факторов, и значительно упрощает работу клиента. Именно в этом сила REST и гипермедиа.

Учитесь бесплатно: На Хекслете есть много бесплатных курсов по программированию, логике, английскому языку и различным инструментам для разработки

Источник

REST API: что это такое простыми словами, примеры запросов, варианты использования сервиса, методы

В этой статье мы разберем оболочку REST API, расскажем, что это такое простыми словами, как работает система.

Так называется способ взаимодействия и обмена данными сервера. Большинство крупных компаний разрабатывают этот интерфейс для внутреннего использования или для своих клиентов. Подобная технология способна обеспечить сообщение между двумя системами. Сейчас этот подход сумел вытеснить практически все остальные, включая дизайны, которые были основаны на SOAP.

Что такое REST API

Это английская аббревиатура, которая расшифровывается и переводится как передача состояния представления. Web-службы, которые пользуются системой Representational State Transfer, применяют термин RESTful. Отличие этого архитектурного стиля от других состоит в том, что у него нет единого стандарта, однако при этом допустимо использовать XML, HTTP, JSON и URL.

Representational State Transfer разработали еще в 2000 году, но с того момента он очень развился и сейчас стал одним из самых популярных, отодвинув на задний план аналогичные.

Чтобы объяснить суть Restful API для чайников, можно представить калькулятор на любом компьютере. Когда мы нажимаем на кнопки, желая получить расчеты, также начинают действовать и скрытые функции, которые в итоге и помогают получить результат. А когда сервис получает ответ, он выводит его на экран в виде готовой цифры в графическом интерфейсе.

Здесь архитектура работает аналогичным образом. При нажатии на кнопку выполняются разные операции по обработке и передаче информации. Они могут не просто получать данные из одной сети, а способны вызывать и обращаться к удаленным серверам, чтобы взять нужное у них.

В качестве примера стоит привести кнопку Facebook, которая умеет задействовать соцсеть, или видео на Youtube, его тоже запускает веб-версия API.

Как работает

В первую очередь стоит разобраться, как действует подход:

Суть работы алгоритма заключается в паре действий, в зависимости от типа запроса. От работы сервера зависит функционал и способности архитектуры. Есть 4 основных вида в отношении информации:

В качестве пакета обычно отправляется JSON массив на указанный конкретный URL. Там срабатывает так называемая функция, а в зависимости от уже отправленных данных и текущего запроса начинается определенное действие. При этом не имеет значения, с какого устройства выслана информация — мобильное приложение или браузер компьютера.

Что такое API

По сути, это интерфейс программирования, который обладает следующими признаками:

Таким образом, это своеобразная созданная человеком архитектура, которая разработана с помощью ограничений и расширений. Если их использовать, то мы получаем стиль, который оптимизирован под заданные цели.

В его задачи входит представлять состояние передачи:

Протокол по типу концентрированного REST API, работающий по HTTP равно качественным веб-сервисам

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

Те варианты, которые применяются для транслирования, тоже можно учитывать как «веб-сервисы». Клиент, который пользуется этим, способен запросить все что угодно, а сервер ему отвечает и предоставляет результаты. При этом задействуется любой удобный язык программирования или подходящие платформы.

Это вообще лучшая часть всего созданного в компьютерном мире. Так как подобные веб-сервисы не зависят от языков, то могут совмещаться с самыми разными системами. Когда API документируется, то неважно, чем пользовались разработчики при его создании — Ruby это был, Java или Python или что-то принципиально другое. Все запросы высылаются через один и тот же HTTP, решения приходят таким же способом.

Дело в том, что этот протокол используется именно для реализации передачи, это своеобразный шаблон. Сервер способен говорить на любом языке программирования, информацию он анализирует по-своему, при этом сам не находится в зависимости от них, поэтому приходящая и уходящая информация схожа.

SOAP стоит отнести к предкам интерфейсов по типу REST API

Еще перед тем, как прикладное программирование нового поколения стало популярным и везде используемым, у него был аналог — SOAP. Он был максимально распространен. А чтобы понять разницу между этим интерфейсами, стоит разобраться в истоках.

SOAP — это протокол, который работает по заранее определенному стандарту. Ему для работы требуется XML, это определит формат, в котором будут отражаться входящие и исходящие запросы. Так как это стандартная вещь, подвид можно определить, если использовать файл WSDL — он помогает расшифровывать язык, на котором пишут веб-службы. Он определяет, есть ли атрибуты или какие-то расширенные элементы в передающихся сообщениях. Это машиночитаемая часть функционирования сети, поэтому пользуются им только сервера, которые действуют и общаются, чтобы облегчить связь.

Все сообщения внутри SOAP собираются в своеобразные «конвертики», в которых есть заголовок и основное тело. Все это «пакуется» при помощи заранее сформированной схемы по принципу XML.

Основная проблема этой системы в том, что формат, который используется для передачи, излишне тяжелый. Это вызывает серьезные проблемы в выполняемых сценариях на мобильных устройствах, задерживает загрузку, делает слишком медленной обработку. Там, где пропускная способность очень важна, эту схему использовать нецелесообразно. Это одна из причин, по которой был придуман и создан rest-сервис.

Источник

SAP@Pitroff.Ru

“REST” – это не про “отдых”.
Часть первая: что такое архитектура REST?

Disclaimer:
1) Часть 1 – теоретическая, может быть скучно :);
2) если вы до этого сталкивались и работали с протоколом HTTP (знаете, как устроен, формат запроса/ответа) – проблем с пониманием REST у вас возникнуть не должно. Если не уверены – рекомендую сначала почитать
про HTTP на Википедии.

Из википедии: REST (Representational State Transfer) — архитектурный стиль взаимодействия компонентов распределённого приложения в сети.

Для веб-сервисов или API, построенных с учётом REST (то есть не нарушающих накладываемых им ограничений), применяют термин «RESTful».

Термин REST был введен в 2000 году Роем Филдингом, одним из авторов HTTP-протокола.

REST – достаточно распространенный в интернете способ взаимодействия клиентских приложений и сервисов. Сервис, написанный с учетом ограничений и правил REST принято называть RESTful.

Очень важно следующее: REST – это НЕ протокол или стандарт.
В отличие от веб-сервисов на основе SOAP, не существует утвержденного или принятого официально стандарта для RESTful сервисов. REST является архитектурой, в то время как SOAP является протоколом.

То есть REST – это набор принципов и ограничений взаимодействия клиента и сервера в сети интернет, использующий существующие стандарты (HTTP протокол, стандарт построения URL, форматы данных JSON и XML) в ходе взаимодействия.

Правила и ограничения REST-архитектуры

В REST есть шесть основных ограничений:

1) Модель взаимодействия клиент-сервер.

Если говорить простыми словами, то нужно разделить требования и желания клиента/пользователя от возможностей и логики работы сервиса.

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

2) Отсутствие состояния.

3) Кэширование.

Речь о том, что пара “запрос-ответ” может быть помечена как кэшируемая и храниться на стороне пользователя. Можно провести аналогию с кэшированием веб-страниц – скачав однажды, ее можно просматривать, не обращаясь заново к серверу.
Однако, если запрос помечен как “не кэшируемый” – то при каждом новом запросе клиент должен вызывать сервер.

4) Единообразие интерфейса.

Чтобы отделить один ресурс(сервис) от другого используются запросы/ссылки (URI).

Пример: информация по ISBN-коду книги в библиотеке – http://library.net/books/info/
продление книги по ISBN – http://library.net/books/prolong/

Пример неподходящего разделения: http://library/books/operation, где операция и код книги должны быть в теле запроса.

По простому: если мы получили мета-данные по объекту (из предыдущего примера – код ISBN книги) – то можем сделать с этим объектом любую операцию из состава API.

Каждое сообщение содержит достаточно информации, чтобы понять каким образом его обрабатывать. В это входит как техническая обработка (например, возврат в HTTP-заголовке типа содержимого ответа), так и смысловая часть сообщения.

Гипермедиа – это расширение термина гипертекст. Если упростить – то это все интерактивные объекты сети: рисунки, схемы, видео (пример – youtube), текст и ссылки.

5) Слои.

Клиент не должен знать, работает ли он с конечной точкой, или с цепочкой/иерархией серверов. То есть REST предусматривает возможность кластерной/распределенной работы серверной части, но при этом для клиента сервис должен оставаться цельным и не требовать дополнительных данных/действий от клиента.

6) Код по требованию (необязательное ограничение).

Тут разработчик архитектуры REST предложил следующее – по запросу, сервис должен отдавать исполняемый код в виде апплета или сценария, для выполнения на стороне клиента. На практике – практически не используется.

RESTful сервис

С точки зрения пользователя, RESTful сервисы – это ресурсы сети, которыми может быть всё, что можно поименовать и представить.

Сервисы описывают себя сами. Ну или пытаются :), но чем логичней и понятней система наименования (url) – тем удобнее работать с API.
Поэтому api/books/get/ISBN/2-266-11156 лучше и понятней, с точки зрения клиента, чем /api?obj=books&func=get&search=ISBN&number=2-266-11156

В ресурсах содержатся ссылки на другие ресурсы (гиперсреда). То есть, получив первичную информацию по объекту, в составе ответа может быть ссылка на ресурс, дающий полную информацию по этому объекту.

Пример: Используя REST API находим книгу по url api/books/get/ISBN/2-266-11156. В ответе сервис высылает блок информации, в нем есть элемент infolink, содержащий ссылку api/books/info/2-266-11156.

Взаимодействие с ресурсами осуществляется с помощью вызова URL ресурса и стандартных команд HTTP (GET, POST, PUT и DELETE). Эти операции обычно соответствуют операциям с объектом, например, так:

Ответ сервис также отправляет в виде кода возврата HTTP, например:

На деле кодов возврата у HTTP существенно больше (wiki – HTTP codes). Также дополнительные данные об ошибке могут передаваться в теле ответа.

Формат данных, передаваемых между клиентом и сервисом указывается с помощью заголовка HTTP – параметр типа содержимого Content-Type. Обычно это JSON или XML, но могут быть разнообразными (например, JPG, PNG – для сервиса обработки графики).

JSON vs XML

Для специалистов, работающих с SAP PI/PO, XML – это практически второй родной язык. 🙂 JSON же в мире SAP практически не используется, поэтому уделю немного внимания этой теме.

Сходство JSON и XML:
Это понятные языки – их можно читать без специального ПО и понимать содержимое;
Это иерархичные языки – данные организованы при помощи различных уровней вложенности;
Для получения данных/значений XML/JSON нужно разобрать – подвергнуть “парсингу”,”распарсить”.

Основные различия:
JSON компактнее (данные в формате JSON имеют меньший размер, чем в XML);
JSON быстрее в чтении/передаче данных;
JSON позволяет вариативность типов/структур (например, в JSON-схеме разрешены элементы, имеющие один из нескольких типов – в схеме данных можно определить, что элемент price может быть текстом, а может быть структурой из двух элементов). После привычки к строгости XML вариативность JSON сложно понять и принять. 🙂

Использование REST API

На данный момент практически каждый крупный интернет-ресурс имеет свой REST API:

А вот как с ним работать – будет в следующей серии. 🙂

2 thoughts on “ “REST” – это не про “отдых”.
Часть первая: что такое архитектура REST? ”

Ура, появляются новые статьи 🙂 Жду вторую часть.

Источник

Руководство для начинающих по HTTP и REST

Russian (Pусский) translation by Yuri Yuriev (you can also view the original English article)

В этом введении мы познакомимся с принципами разработки REST, лежащими в основе HTTP и использованию их мощи для создания интерфейсов, которые могут выполняться практически с любого устройства или операционной системы.

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

Почему REST?

После первоначального обзора мы рассмотрим каждый из строительных блоков HTTP: URL-адреса, HTTP-команды и коды ответов. Мы также рассмотрим, как использовать их в RESTful. Попутно мы проиллюстрируем теорию примером приложения, которое имитирует процесс отслеживания данных, связанных с клиентами компании через веб-интерфейс.

В HTTP есть две разные роли: сервер и клиент. Как правило, клиент всегда инициирует разговор; сервер отвечает. HTTP основан на тексте; то есть сообщения по сути являются битами текста, хотя тело сообщения может также содержать другие носители. Использование текста позволяет легко отслеживать обмен HTTP.

HTTP-сообщения состоят из заголовка и тела. Тело часто может оставаться пустым; оно содержит данные, которые вы хотите передать по сети, чтобы использовать их в соответствии с инструкциями в заголовке. Заголовок содержит метаданные, например информацию о кодировке; но, в случае запроса, он также содержит важные HTTP-методы. В стиле REST вы обнаружите, что данные заголовка часто более значимы, чем тела.

Шпионство HTTP на работе

Другим полезным способом ознакомиться с HTTP является использование выделенного клиента, такого как cURL.

После установки cURL введите:

будет идентифицировать всех клиентов, в то время как

определяет клиента с именем ‘Jim’, предполагая, что он единственный с таким именем.

В этих примерах мы обычно не включаем hostname в URL, так как это не имеет никакого отношения к организации интерфейса. Тем не менее, hostname важно для того, чтобы идентификатор ресурса был уникальным во всей сети. Мы часто говорим, что вы отправляете запрос на ресурс к host. Хост включается в заголовок отдельно от пути ресурса, который идёт прямо над заголовком запроса:

Ресурсы лучше всего рассматривать как существительные. Например, следующее не RESTful:

Это связано с тем, что для описания действия используется URL-адрес. Это довольно фундаментальный момент в различиях систем RESTful от систем без RESTful.

Наконец, URL-адреса должны быть максимально точными; всё, что необходимо для уникальной идентификации ресурса, должно быть в URL-адресе. Вам не нужно включать в запрос данные, идентифицирующие ресурс. Таким образом, URL-адреса выступают в качестве полной карты всех данных, обрабатываемых приложением.

Но как вы определяете действие? Например, как сообщить, что вы хотите создать новую запись клиента вместо её получения? Именно здесь вступают в действие глаголы HTTP.

Глаголы HTTP

Каждый запрос указывает определенный HTTP глагол или метод в заголовке запроса. Это первое слово в заголовке запроса. Например,

означает, что используется метод GET, а

Глаголы HTTP сообщают серверу, что делать с данными, указанными URL.

Запрос PUT используется, когда вы хотите создать или обновить ресурс, указанный URL-адресом. Например,

DELETE

DELETE должен выполнять противоположное PUT ; его следует использовать, если вы хотите удалить ресурс, указанный URL-адресом запроса.

Запросы PUT легко используются вместо запросов POST и наоборот. Некоторые системы используют только один, некоторые используют POST для создания операций и PUT для операций обновления (поскольку с запросом PUT вы всегда указываете полный URL-адрес), некоторые используют POST для обновлений и PUT для создания.

Классификация методов HTTP

Помните: именно вы, программист, в конечном счете решаете, что происходит, когда используется определённый HTTP-метод. В реализациях HTTP нет ничего, что автоматически приведёт к созданию ресурсов, их перечислению, удалению или обновлению. Вы должны быть осторожны, чтобы правильно применять HTTP-протокол и вводить эту семантику самостоятельно.

Представительства

HTTP-клиент и HTTP-сервер обмениваются информацией о ресурсах, определённых URL-адресами.

Мы можем суммировать то, что мы узнали до сих пор, следующим образом: HTTP-клиент и HTTP-сервер обмениваются информацией о ресурсах, определённых URL-адресами.

Заголовки HTTP, содержащие метаданные, жёстко определяются спецификацией HTTP; они могут содержать только простой текст и должны быть отформатированы определённым образом.

Тело может содержать данные в любом формате, и именно здесь видна сила HTTP. Вы знаете, что можете отправлять простой текст, изображения, HTML и XML на любом человеческом языке. Через метаданные запроса или различные URL-адреса вы можете выбирать между различными представлениями для одного и того же ресурса. Например, вы можете отправить веб-страницу в браузеры и JSON в приложения.

HTTP-ответ должен указывать тип содержимого body. Это делается в заголовке, в поле Content-Type; например:

Для простоты наше приложение только отправляет JSON туда и обратно, но приложение должно быть спроектировано таким образом, чтобы вы могли легко изменять формат данных, чтобы адаптироваться для разных клиентов или предпочтений пользователя.

Библиотеки клиента HTTP

Чтобы поэкспериментировать с различными методами запроса, вам нужен клиент, который позволит указать, какой метод использовать. К сожалению, формы HTML не подходят для счёта, так как они позволяют делать только запросы GET и POST. В реальной жизни API-интерфейсы доступны программно через отдельное клиентское приложение или через JavaScript в браузере.

Именно поэтому в дополнение к серверу важно иметь хорошие возможности HTTP-клиента на выбранном вами языке программирования.

Очень популярная клиентская HTTP-библиотека, опять же, cURL. Вы уже были ознакомлены с командой cURL ранее в этом уроке. CURL включает в себя как автономную программу командной строки, так и библиотеку, которая может использоваться различными языками программирования. В частности, cURL является, чаще всего, идеальным решением HTTP-клиента для разработчиков PHP. Другие языки, такие как Python, предлагают больше собственных клиентских HTTP-библиотек.

Настройка примера приложения

Я хочу показать как можно более низкий уровень функциональности.

Что касается серверов, наиболее распространенным вариантом является Apache с mod_php, но вы можете использовать любые альтернативы, которые вам удобны. Существует пример конфигурации Apache, который содержит правила перезаписи, которые помогут вам быстро настроить приложение. Все запросы к любому URL, начиная с /clients/, должны быть направлены в наш файл server.php.

В Apache вам нужно включить mod_rewrite и поместить прилагаемую конфигурацию mod_rewrite где-нибудь в вашей конфигурации Apache или в ваш файл .htacess. Таким образом, server.php будет отвечать на все запросы, поступающие с сервера. То же самое должно быть достигнуто с Nginx, или с любым другим сервером, который вы решите использовать.

Как работает пример приложения

Эта переменная содержит имя метода в виде строки, например ‘ GET ‘, ‘ PUT ‘ и далее.

Давайте сначала попытаемся определить, какой URL-адрес был вызван. Мы рассматриваем только URL-адреса, начинающиеся с ‘ clients ‘. Все остальные недействительны.

У нас есть два возможных результата:

Коды ответов

Коды ответа HTTP стандартизируют способ информирования клиента о результате его запроса.

Имейте в виду, что значение кода ответа HTTP не является чрезвычайно точным; это следствие того, что HTTP сам по себе довольно общий. Вы должны попытаться найти код ответа, который наиболее точно соответствует ситуации. Но и не слишком переживайте, если не сможете найти точное соответствие.

Вот несколько HTTP-кодов ответа, которые часто используются с REST:

200 OK

Этот код ответа указывает, что запрос был успешным.

201 Created

400 Bad Request

404 Not Found

Этот ответ указывает, что необходимый ресурс не найден. Обычно это относится ко всем запросам, которые указывают на URL-адрес без соответствующего ресурса.

401 Unauthorized

Эта ошибка означает, что вам необходимо выполнить проверку подлинности перед доступом к ресурсу.

405 Method Not Allowed

Используемый метод HTTP не поддерживается для этого ресурса.

409 Conflict

Это указывает на конфликт. Например, вы используете запрос PUT для создания одного и того же ресурса дважды.

500 Internal Server Error

Когда всё остальное терпит неудачу; как правило, ответ 500 используется, когда обработка завершается неудачно из-за непредвиденных обстоятельств на стороне сервера, что вызывает ошибку сервера.

Выполнение образца приложения

Давайте начнем с простого извлечения информации из приложения. Нам нужны детали клиента, ‘ jim ‘, поэтому давайте отправим простой запрос GET на URL этого ресурса:

Затем мы можем получить информацию для всех клиентов одновременно:

и вы получите список всех клиентов, содержащих Paul в качестве подтверждения.

Наконец, чтобы удалить клиента:

Вы обнаружите, что возвращённый JSON больше не содержит никаких данных об Anne.

Если вы пытаетесь получить несуществующего клиента, например:

Вы получите ошибку 404, в то время как при попытке создать уже существующего клиента:

вместо этого получите ошибку 409.

Заключение

В общем, чем меньше предположений за пределами HTTP вы делаете, тем лучше.

Важно помнить, что HTTP был задуман для взаимодействия между системами, которые ничто не разделяет, кроме понимания протокола. В целом, чем меньше допущений за пределами HTTP вы делаете, тем лучше: это позволяет широкому кругу программ и устройств получать доступ к вашему API.

Помимо PHP, вы можете принять во внимание следующее:

Среди приложений, которые пытаются придерживаться принципов REST, классическим примером является Atom Publishing Protocol, хотя на самом деле он не используется слишком часто на практике. За современным приложением, основанным на философии использования HTTP в полной мере, обратитесь к Apache CouchDB.

Источник