Что содержит url в rest запросе

Введение в REST API

REST означает REpresentational State Transfer (передача состояния представления). Это популярный архитектурный подход для создания API в современном мире.

Что такое REST?

REST расшифровывается как REpresentational State Transfer. Этот термин первоначально введен Роем Филдингом (Roy Fielding), который также был одним из создателей протокола HTTP. Отличительной особенностью сервисов REST является то, что они позволяют наилучшим образом использовать протокол HTTP. Теперь давайте кратко рассмотрим HTTP.

Протокол HTTP

Когда вы вводите в браузере URL-адрес, например www.google.com, на сервер отправляется запрос на веб-сайт, идентифицированный URL-адресом. Затем этот сервер формирует и выдает ответ. Важным является формат этих запросов и ответов. Эти форматы определяются протоколом HTTP — Hyper Text Transfer Protocol.

Когда вы набираете URL в браузере, он отправляет запрос GET на указанный сервер. Затем сервер отвечает HTTP-ответом, который содержит данные в формате HTML — Hyper Text Markup Language. Затем браузер получает этот HTML-код и отображает его на экране.

Допустим, вы заполняете форму, присутствующую на веб-странице, со списком элементов. В таком случае, когда вы нажимаете кнопку Submit, HTTP-запрос POST отправляется на сервер.

HTTP и RESTful веб-сервисы

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

Ресурс

Ресурс — это ключевая абстракция, на которой концентрируется протокол HTTP. Ресурс — это все, что вы хотите показать внешнему миру через ваше приложение. Например, если мы пишем приложение для управления задачами, экземпляры ресурсов будут следующие:

• Конкретный пользователь
• Конкретная задача
• Список задач

URI ресурса

Когда вы разрабатываете RESTful сервисы, вы должны сосредоточить свое внимание на ресурсах приложения. Способ, которым мы идентифицируем ресурс для предоставления, состоит в том, чтобы назначить ему URI — универсальный идентификатор ресурса. Например:

• Создать пользователя: POST /users
• Удалить пользователя: DELETE /users/1
• Получить всех пользователей: GET /users
• Получить одного пользователя: GET /users/1

REST и Ресурсы

Важно отметить, что с REST вам нужно думать о приложении с точки зрения ресурсов:

• Определите, какие ресурсы вы хотите открыть для внешнего мира;
• Используйте глаголы, уже определенные протоколом HTTP, для выполнения операций с этими ресурсами.

Вот как обычно реализуется служба REST:

• Формат обмена данными: здесь нет никаких ограничений. JSON — очень популярный формат, хотя можно использовать и другие, такие как XML;
• Транспорт: всегда HTTP. REST полностью построен на основе HTTP;
• Определение сервиса: не существует стандарта для этого, а REST является гибким. Это может быть недостатком в некоторых сценариях, поскольку потребляющему приложению может быть необходимо понимать форматы запросов и ответов. Однако широко используются такие языки определения веб-приложений, как WADL (Web Application Definition Language) и Swagger.

REST фокусируется на ресурсах и на том, насколько эффективно вы выполняете операции с ними, используя HTTP.

Компоненты HTTP

HTTP определяет следующую структуру запроса (request):

• строка запроса (request line) — определяет тип сообщения;
• заголовки запроса (header fields) — характеризуют тело сообщения, параметры передачи и прочие сведения;
• тело сообщения (body) — необязательное.

HTTP определяет следующую структуру ответного сообщения (response):

• строка состояния (status line), включающая код состояния и сообщение о причине;
• поля заголовка ответа (header fields);
• дополнительное тело сообщения (body).

Методы HTTP-запроса

Метод, используемый в HTTP-запросе, указывает, какое действие вы хотите выполнить с этим запросом. Важные примеры:

• GET: получить подробную информацию о ресурсе;
• POST: создать новый ресурс;
• PUT: обновить существующий ресурс;
• DELETE: Удалить ресурс.

Код статуса ответа HTTP

Код состояния всегда присутствует в ответе HTTP. Типичные примеры:

• 200 — успех;
• 404 — cтраница не найдена.

— Различия REST и SOAP

На самом деле, сравнивать их немного похоже на сравнение яблок с апельсинами, поскольку SOAP — это формат протокола, основанный на XML, тогда как REST — это архитектурный подход.

REST и SOAP

REST и SOAP на самом деле не сопоставимы. REST — это архитектурный стиль. SOAP — это формат обмена сообщениями. Давайте сравним популярные реализации стилей REST и SOAP.

• Пример реализации RESTful: JSON через HTTP
• Пример реализации SOAP: XML поверх SOAP через HTTP

На верхнем уровне SOAP ограничивает структуры ваших сообщений, тогда как REST — это архитектурный подход, ориентированный на использование HTTP в качестве транспортного протокола.

— Специфика SOAP — это формат обмена данными. С SOAP это всегда SOAP-XML, который представляет собой XML, включающий:

• Envelope (конверт) — корневой элемент, который определяет сообщение и пространство имен, использованное в документе,
• Header (заголовок) — содержит атрибуты сообщения, например: информация о безопасности или о сетевой маршрутизации,
• Body (тело) — содержит сообщение, которым обмениваются приложения,
• Fault — необязательный элемент, который предоставляет информацию об ошибках, которые произошли при обработке сообщений. И запрос, и ответ должны соответствовать структуре SOAP.

— Специфика REST — использование HTTP в качестве транспортного протокола. Он подразумевает наилучшее использование функций, предоставляемых HTTP — методы запросов, заголовки запросов, ответы, заголовки ответов и т. д.

Формат обмена сообщениями

• В SOAP вы используете формат SOAP XML для запросов и ответов.
• В REST такого фиксированного формата нет. Вы можете обмениваться сообщениями на основе XML, JSON или любого другого удобного формата. JSON является самым популярным среди используемых форматов.

Определения услуг

• SOAP использует WSDL (Web Services Description Language) — язык описания веб-сервисов и доступа к ним, основанный на языке XML.
• REST не имеет стандартного языка определения сервиса. Несмотря на то, что WADL был одним из первых предложенных стандартов, он не очень популярен. Более популярно использование Swagger или Open API.

Транспорт

• SOAP не накладывает никаких ограничений на тип транспортного протокола. Вы можете использовать либо Web протокол HTTP, либо MQ.
• REST подразумевает наилучшее использование транспортного протокола HTTP.

Простота реализации

RESTFful веб-сервисы, как правило, гораздо проще реализовать, чем веб-сервисы на основе SOAP.

• REST обычно использует JSON, который легче анализировать и обрабатывать. В дополнение к этому, REST не требует наличия определения службы для предоставления веб-службы.
• Однако в случае SOAP вам необходимо определить свой сервис с использованием WSDL, и при обработке и анализе сообщений SOAP-XML возникают большие накладные расходы.

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

Протокол передачи гипертекста (HTTP) — это основа жизни в Интернете. Он используется каждый раз при передаче документа или в запросе AJAX . Но HTTP на удивление мало известен некоторым веб-разработчикам.

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

Переизданный урок

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

Почему REST?

REST — простой способ организации взаимодействия между независимыми системами.

REST — простой способ организации взаимодействия между независимыми системами. Он пользуется популярностью с 2005 года и вдохновляет дизайн сервисов, таких как API Twitter. Благодаря тому, что REST обеспечивает взаимодействие с такими разнообразными клиентами, как мобильные телефоны и другие веб-сайты. Теоретически, REST не привязан к сети, но почти всегда реализован как таковой и был вдохновлен HTTP. В результате REST можно использовать везде, где возможен HTTP.

Альтернативой является создание относительно сложных соглашений поверх HTTP. Часто это принимает форму новых XML-языков. Самый яркий пример — SOAP. Вам нужно выучить совершенно новый набор соглашений, но вы никогда не используете HTTP в полную силу. Поскольку REST был вдохновлён HTTP и играет на его сильные стороны, это лучший способ узнать, как работает HTTP.

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

HTTP

HTTP — это протокол, который позволяет отправлять документы в Интернете.

HTTP — это протокол, который позволяет отправлять документы в Интернете. Протокол — это набор правил, определяющих, какие сообщения можно обменивать, и какие сообщения являются подходящими ответами для других. Другим распространенным протоколом является POP3, который вы можете использовать для извлечения электронной почты на вашем жёстком диске.

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

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

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

Если вы используете Chrome Developer Tools или Firefox с расширением Firebug, щелкните на панели Net и установите его в enabled . После этого у вас будет возможность просматривать информацию о HTTP-запросах по мере вашего поиска. Например:

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

cURL — это инструмент command line, который доступен во всех основных операционных системах.

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

curl -v google.com

Будет отображен полный диалог HTTP. Запросам предшествует > , а ответам предшествует < .

URLS

URL — это, как вы определяете то, на чём вы хотите работать. Мы говорим, что каждый URL-адрес идентифицирует ресурс. Это те же самые URL-адреса, которые назначены веб-страницам. Фактически, веб-страница — это тип ресурса. Давайте рассмотрим более экзотический пример с нашим образцом приложения, которое управляет списком клиентов компании:

/clients

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

/clients/jim

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

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

GET /clients/jim HTTP/1.1

Host: example.com

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

/clients/add

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

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

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

Глаголы HTTP

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

GET / HTTP/1.1

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

DELETE /clients/anne HTTP/1.1

означает использование метода DELETE .

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

Глаголы HTTP сообщают серверу, что делать с данными, указанными URL. Запрос может ещё содержать дополнительную информацию в своем теле, которая может потребоваться для выполнения операции — например, данные, которые вы хотите сохранить с ресурсом. Эти данные можно указать в cURL с параметром -d .

Если вы когда-либо создавали HTML-формы, то знакомы с двумя из наиболее важных HTTP-глаголов: GET и POST . Но есть гораздо больше доступных HTTP-глаголов. Наиболее важными для построения RESTful API являются GET , POST , PUT и DELETE . Доступны другие методы, такие как HEAD и OPTIONS , но они более редки (если вы хотите знать обо всех других методах HTTP, официальным источником является IETF).

GET

GET — это самый простой тип HTTP-запроса; которым браузер пользуется каждый раз, когда вы нажимаете ссылку или вводите URL-адрес в адресную строку. Он инструктирует сервер передавать клиенту данные, идентифицированные URL-адресом. Никогда не последует изменений данных на стороне сервера в результате запроса GET . В этом смысле GET -запрос доступен только для чтения, но, конечно, как только клиент получит данные, он может самостоятельно выполнять любые операции с ними, например, форматировать для отображения.

PUT

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

PUT /clients/robin

может создать клиента с именем Robin на сервере. Вы заметите, что REST полностью независим от бэкэнда; в запросе нет ничего, что информирует сервер о том, как данные должны создаваться — просто так должно быть. Это позволяет вам легко менять базовую технологию по необходимости. Запросы PUT содержат данные для использования при обновлении или создании ресурса в body. В cURL вы можете добавить данные в запрос с помощью -d .

curl -v -X PUT -d "some text" 

DELETE

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

curl -v -X DELETE /clients/anne

Это приведёт к удалению всех данных, связанных с ресурсом, идентифицированных /clients/anne .

POST

POST используется, когда обработка, которую вы хотите выполнить на сервере, должна повторяться, если запрос POST повторяется (то есть, они не являются идемпотентными, подробнее об этом ниже). Кроме того, POST -запросы должны вызывать обработку body запроса как подчинённого URL-адреса, который вы отправляете.

POST /clients/

не должен вызывать изменение ресурса в /clients/ сам, но ресурс URL начинается с него /clients/ . Например, он может добавить в список нового клиента, с id , сгенерированным сервером.

/clients/some-unique-id

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

Часто запросы POST используются для запуска операций на сервере, которые не вписываются в парадигму Create/Update/Delete ; но это, однако, выходит за рамки REST . В нашем примере мы будем полностью придерживаться PUT .

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

Безопасные и небезопасные методы:

безопасными являются методы, которые никогда не изменяют ресурсы. Единственными безопасными методами, из четырёх перечисленных выше, является GET . Другие небезопасны, так как они могут привести к модификации ресурсов.

Idempotent методы:

Эти методы достигают того же результата, независимо от того, сколько раз запрос повторяется: это GET , PUT и DELETE . Единственным неидемпотентным методом является POST . PUT и DELETE , считающиеся идемпотентами, могут быть неожиданными, хотя, на самом деле, это довольно легко объяснить: повторение метода PUT с точно таким же body должно модифицировать ресурс таким образом, чтобы он оставался идентичным описанному в предыдущем запросе PUT : ничего не изменится! Аналогичным образом, нет смысла дважды удалять ресурс. Из этого следует, что независимо от того, сколько раз запрос PUT или DELETE повторяется, результат должен быть таким же, как если бы это было сделано только один раз.

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

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

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

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

Мы говорим, что запрос и ответ содержат представление ресурса. Под представлением мы подразумеваем информацию в определённом формате о состоянии ресурса или о том, каким это состояние должно быть в будущем. Оба, и header, и body — являются частями представления.

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

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

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

Content/Type: application/json

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

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

cURL — это, чаще всего, HTTP-решение для PHP-разработчиков.

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

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

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

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

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

Наш пример PHP-приложения чрезвычайно тощ. Я хочу выставить как можно более низкоуровневую функциональность, без какой-либо магии framework . Я также не хотел использовать настоящий API, например, Twitter, потому что они могут неожиданно меняться, вам нужно настроить аутентификацию, что может быть проблемой и вы не сможете изучить реализацию.

Чтобы запустить пример приложения, вам необходимо установить PHP5 и веб-сервер с механизмом для запуска PHP. Текущая версия должна быть не ниже версии 5.2, чтобы иметь доступ к функциям json_encode () и json_decode () .

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

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

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

Есть два ключа по обработке запросов REST. Первый ключ — инициировать различную обработку, в зависимости от метода HTTP, даже когда URL-адреса одинаковы. В PHP в глобальном массиве $ _SERVER есть переменная, которая определяет, какой метод был использован для выполнения запроса:

$_SERVER['REQUEST_METHOD'] 

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

Другой ключ — узнать, какой URL был запрошен. Для этого мы используем другую стандартную переменную PHP:

$_SERVER['REQUEST_URI'] 

Эта переменная содержит URL-адрес, начинающийся с первой косой черты. Например, если имя хоста — ‘ example.com ‘, ‘ http://example.com/ ‘ вернётся ‘ / ‘, как ‘ http://example.com/test/ ‘ вернётся ‘ /test/ ‘.

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

$resource = array_shift($paths); 

Что такое RESTful API?

RESTful API — это интерфейс,используемые двумя компьютерными системами для безопасного обмена информацией через Интернет. Большинство бизнес-приложений должны взаимодействовать с другими внутренними и сторонними приложениями для выполнения различных задач. Например, чтобы генерировать ежемесячные платежные ведомости, ваша внутренняя бухгалтерская система должна обмениваться данными с банковской системой вашего клиента, чтобы автоматизировать выставление счетов и взаимодействовать с внутренним приложением по учету рабочего времени. RESTful API поддерживают такой обмен информацией, поскольку они следуют безопасным, надежным и эффективным стандартам программного взаимодействия.

Что такое API?

Интерфейс прикладного программирования (API) определяет правила, которым необходимо следовать для связи с другими программными системами. Разработчики внедряют или создают API-интерфейсы, чтобы другие приложения могли программно взаимодействовать с их приложениями. Например, приложение с табелем рабочего времени содержит API, который запрашивает полное имя сотрудника и диапазон дат. Получив эту информацию, интерфейс внутренне обрабатывает табель рабочего времени сотрудника и возвращает количество часов, отработанных за указанный период.

Таким образом, сетевой API функционирует как шлюз между клиентами и ресурсами в Интернете.

Клиенты

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

Ресурсы

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

Что такое REST?

Representational State Transfer (REST) — это программная архитектура, которая определяет условия работы API. Первоначально REST создавалась как руководство для управления взаимодействиями в сложной сети, такой как Интернет. Архитектуру на основе REST можно использовать для поддержки высокопроизводительной и надежной связи в требуемом масштабе. Ее можно легко внедрять и модифицировать, обеспечивая прозрачность и кросс-платформенную переносимость любой системы API.

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

Ниже приведены некоторые принципы архитектурного стиля REST:

Единый интерфейс

Единый интерфейс является конструктивной основой любого веб-сервиса RESTful. Это указывает на то, что сервер передает информацию в стандартном формате. Отформатированный ресурс в REST называется представлением. Этот формат может отличаться от внутреннего представления ресурса в серверном приложении. Например, сервер может хранить данные в виде текста, но отправлять их в формате представления HTML.

Единый интерфейс накладывает четыре архитектурных ограничения:

1. Запросы должны идентифицировать ресурсы. Это происходит за счет единого идентификатора ресурсов.
2. Клиенты имеют достаточно информации в представлении ресурса, чтобы при желании изменить или удалить ресурс. Сервер выполняет это условие, отправляя метаданные, которые дополнительно описывают ресурс.
3. Клиенты получают информацию о дальнейшей обработке представлений. Сервер реализует это, отправляя описательные сообщения, где содержатся метаданные о том, как клиент может использовать их оптимальным образом.
4. Клиенты получают информацию обо всех связанных ресурсах, необходимых для выполнения задачи. Сервер реализует это, отправляя гиперссылки в представлении, чтобы клиенты могли динамически обнаруживать больше ресурсов.

Отсутствие сохранения состояния

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

Многоуровневая система

В многоуровневой системной архитектуре клиент может подключаться к другим авторизованным посредникам между клиентом и сервером и по-прежнему получать ответы от сервера. Серверы также могут передавать запросы другим серверам. Вы можете спроектировать свою веб-службу RESTful для работы на нескольких серверах с несколькими уровнями (безопасностью, приложениями и бизнес-логикой), совместно выполняющих клиентские запросы. Эти уровни остаются невидимыми для клиента.

Емкость кэша

Веб-службы RESTful поддерживают кэширование, то есть процесс сохранения некоторых ответов на клиенте или на посреднике для сокращения времени ответа сервера. Например, вы заходите на веб-сайт с общими изображениями верхнего и нижнего колонтитулов на каждой странице. Каждый раз, когда вы посещаете новую страницу веб-сайта, сервер должен повторно отправлять одни и те же изображения. Чтобы избежать этого, клиент кэширует или сохраняет эти изображения после первого ответа, а затем использует изображения из кэша. Веб-службы RESTful управляют кэшированием с помощью ответов API, которые определяют себя как кэшируемые или некэшируемые.

Код по запросу

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

В чем заключаются преимущества RESTful API?

RESTful API обладает следующими преимуществами:

Возможность масштабирования

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

Гибкость

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

Независимость

REST API не зависит от используемой технологии. Вы можете создавать как клиентские, так и серверные приложения на разных языках программирования, не затрагивая структуру API. Также можно изменить базовую технологию на любой стороне, не влияя на обмен данными.

Как работает RESTful API?

Базовый принцип работы RESTful API совпадает с принципом работы в Интернете. Клиент связывается с сервером с помощью API, когда ему требуется какой-либо ресурс. Разработчики описывают принцип использования REST API клиентом в документации на API серверного приложения. Ниже представлены основные этапы запроса REST API:

1. Клиент отправляет запрос на сервер. Руководствуясь документацией API, клиент форматирует запрос таким образом, чтобы его понимал сервер.
2. Сервер аутентифицирует клиента и подтверждает, что клиент имеет право сделать этот запрос.
3. Сервер получает запрос и внутренне обрабатывает его.
4. Сервер возвращает ответ клиенту. Ответ содержит информацию, которая сообщает клиенту, был ли запрос успешным. Также запрос включает сведения, запрошенные клиентом.

Сведения о запросе и ответе REST API могут немного различаться в зависимости от того, как разработчики проектируют API.

Что содержит клиентский запрос RESTful API?

API RESTful требует, чтобы запросы содержали следующие основные компоненты:

Уникальный идентификатор ресурса

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

Метод

Как правило, разработчики реализуют RESTful API с помощью протокола передачи гипертекста (HTTP). Метод HTTP сообщает серверу, что ему необходимо сделать с ресурсом. Ниже приведены четыре распространенных метода HTTP:

Клиенты используют GET для доступа к ресурсам, расположенным на сервере по указанному URL. Они могут кэшировать запросы GET и отправлять параметры в запросе RESTful API, чтобы сообщить серверу о необходимости фильтровать данные перед отправкой.

Клиенты используют POST для отправки данных на сервер. При этом они включают в запрос представления данных. Отправка одного и того же запроса POST несколько раз имеет побочный эффект — многократное создание одного и того же ресурса.

Клиенты используют PUT для обновления существующих на сервере ресурсов. В отличие от POST, отправка одного и того же запроса PUT несколько раз дает один и тот же результат в веб-службе RESTful.

DELETE

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

Заголовки HTTP

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

Данные

Запросы REST API могут включать данные для успешной работы POST, PUT и других методов HTTP.

Параметры

Запросы RESTful API могут включать параметры, которые предоставляют серверу более подробную информацию о необходимых действиях. Ниже приведены некоторые типы параметров:

• Параметры пути, которые определяют детали URL.
• Параметры запроса, которые запрашивают дополнительную информацию о ресурсе.
• Параметры cookie, которые быстро аутентифицируют клиентов.

Что такое методы аутентификации RESTful API?

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

RESTful API поддерживает четыре распространенных метода аутентификации:

HTTP-аутентификация

HTTP определяет некоторые схемы аутентификации, которые можно использовать при реализации REST API. Ниже представлены две такие схемы:

Базовая аутентификация

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

Аутентификация носителя

Аутентификация носителя — это процесс предоставления управления доступом носителю токена. Как правило, токен носителя представляет собой зашифрованную строку символов, которую сервер генерирует в ответ на запрос входа в систему. Клиент отправляет токен в заголовках запроса для доступа к ресурсам.

Ключи API

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

OAuth

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

Что содержит ответ сервера RESTful API?

Принципы REST требуют, чтобы ответ сервера содержал следующие компоненты:

Строка состояния

Строка состояния содержит трехзначный код состояния, который сообщает об успешном или неудачном выполнении запроса. Например, коды 2XX указывают на успешное выполнение, а коды 4XX и 5XX — на ошибки. Коды 3XX указывают на перенаправление URL.

Ниже приведены некоторые распространенные коды состояния:

• 200: общий ответ об успешном выполнении
• 201: ответ об успешном выполнении метода POST
• 400: неверный запрос, который сервер не может обработать
• 404: ресурс не найден

Текст сообщения

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

Заголовки

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

Как AWS может помочь в управлении RESTful API?

Шлюз API Amazon – это полностью управляемый сервис для разработчиков, предназначенный для создания, публикации, обслуживания, мониторинга и обеспечения безопасности API в любых масштабах. API Gateway позволяет создавать RESTful API для приложений двусторонней связи в реальном времени.

С помощью API Gateway можно:

• Предоставить пользователям высокую производительность при запросах и ответах API.
• Разрешить доступ к API с помощью AWS Identity and Access Management (IAM) и Amazon Cognito, которые обеспечивают встроенную поддержку OAuth.
• Запускать несколько версий одного и того же API одновременно с помощью API Gateway, что позволяет быстро дорабатывать, тестировать и запускать новые версии.
• Отслеживать метрики производительности и информацию о запросах API, задержке данных и частоте ошибок из API Gateway.

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

Советы по REST API

Будь то RESTful или нет (в соответствии с шестью ограничениями, описанными ранее), вот несколько рекомендованных REST концепций, которые помогут построить более хорошие и удобные сервисы:

Используйте HTTP-глаголы, чтобы ваши запросы имели понятное значение

Пользователи API должны иметь возможность отправлять команды GET, POST, PUT и DELETE, что значительно повышает ясность того, что делает запрос.

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

GET Прочитать конкретный ресурс (по идентификатору) или набор ресурсов PUT Обновить конкретный ресурс (по идентификатору) или набор ресурсов. Также может использоваться для создания определенного ресурса, если идентификатор ресурса известен заранее DELETE Удалить конкретный ресурс по идентификатору POST Создать новый ресурс. Также универсальное действие для операций, которые не вписываются в другие категории

Примечание

GET-запросы не должны изменять данные базовых ресурсов. При этом может выполняться отслеживание, приводящее к обновлению данных, но данные ресурса, идентифицированного данным URI, не должны изменяться.

Давайте ресурсам продуманные имена

Создание хорошего API — это на 80% искусство и на 20% наука. Создание иерархии осмысленных URL-адресов относится к искусству. Рациональное наименование ресурсов (названия которых представляют собой просто URL-пути, такие как /customers/12345/orders) улучшает понимание того, что делает данный запрос.

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

Вот несколько простых правил для дизайна URL-пути (имени ресурса):

• Используйте идентификаторы в URL-адресах, а не в строке запроса. Использование параметров строки запроса отлично подходит для фильтрации, но не для имен ресурсов
  Хорошо: /users/12345
  Плохо: /api?type=user&id=23
• URL-адреса иерархичны, пользуйтесь этим для задания структуры ресурсов
• Дизайн сервиса должен быть ориентирован на ваших клиентов, а не на ваши данные
• Имена ресурсов должны быть существительными. Избегайте глаголов в именах ресурсов, это позволит сделать их яснее. Используйте методы HTTP, чтобы указать, какое действие выполняет запрос
• Используйте множественное число в соответствующих сегментах URL-адресов, чтобы обеспечить согласованность URI вашего API во всех HTTP-методах, применяя метафору коллекции
  Хорошо: /customers/33245/orders/8769/lineitems/1
  Плохо: /customer/33245/order/8769/lineitem/1
• Избегайте использования наборов слов в URL-адресах (например, customer_list в качестве ресурса). Используйте множественное число для названий коллекций
  Хорошо: /customers
  Плохо: /customer_list
• Используйте строчные буквы в URL, разделяя слова подчеркиванием («_») или дефисом («-«). Некоторые серверы игнорируют регистр, поэтому лучше четко придерживаться нижнего регистра
• Старайтесь, чтобы URL-адреса были как можно короче и содержали как можно меньше сегментов

Используйте коды HTTP-ответов для указания статуса

Коды ответа являются частью спецификации HTTP. Для описания самых распространенных ситуаций существует большой набор HTTP-ответов.

Поскольку наши RESTful сервисы следуют спецификации HTTP, наши веб-API должны возвращать коды состояний HTTP. Например, когда ресурс успешно создан с помощью запроса POST, API должен вернуть код состояния HTTP 201. Полный список возможных кодов состояния HTTP c подробным описанием доступен здесь

Top 10 кодов состояния HTTP-ответа:

200 ОК Код, указывающий на успешное выполнение запроса и чаще всего встречающийся на практике 201 CREATED Ресурс успешно создан (через POST или PUT). Установите заголовок Location со ссылкой на вновь созданный ресурс (при POST). Тело ответа может быть как пустым, так и содержать что-то 204 NO CONTENT Запрос выполнен успешно, но в теле ответа нет данных. Часто используется для операций DELETE и PUT 400 BAD REQUEST Общая ошибка, когда при выполнении запроса возникает недопустимое состояние. Примеры — ошибки проверки домена, отсутствующие данные и т.д. 401 UNAUTHORIZED Код ошибки для отсутствующего или недопустимого токена аутентификации 403 FORBIDDEN Код ошибки, когда пользователь не авторизован для выполнения операции или ресурс недоступен по какой-либо причине (например, ограничения по времени и т.п.) 404 NOT FOUND Этот код используется, когда запрошенный ресурс не найден. Ресурс не существует, либо была ошибка 401 или 403, которую по соображениям безопасности сервис хочет скрыть 405 METHOD NOT ALLOWED Используется для указания на то, что запрошенный URL-адрес существует, но используемый HTTP-метод неприменим. Например, POST /users/12345, где API не поддерживает создание ресурсов таким образом (с предоставленным идентификатором). При возврате ошибки 405 должен быть установлен HTTP-заголовок Allow, указывающий на поддерживаемые методы HTTP. В примере выше заголовок выглядел бы как “Allow: GET, PUT, DELETE” 409 CONFLICT Этот код ошибки отправляется всякий раз, когда выполнение запроса может привести к конфликту ресурсов. Примеры таких ситуаций — двойные записи, например, попытка создать двух клиентов с одинаковой информацией; удаление корневых объектов, когда не поддерживается каскадное удаление 500 INTERNAL SERVER ERROR Никогда не отправляйте этот код вручную. Это общая ошибка, когда на стороне сервера выбрасывается какое-то исключение. Этот код должен использоваться только для ошибок, которые пользователь не может устранить со своей стороны

XML и JSON

Если вы не работаете в строго стандартизированной и регулируемой отрасли, лучше поддерживать JSON. Но если вас ничто не сковывает, позвольте пользователям выбирать в каком формате получать данные — JSON или XML. У пользователей должна быть возможность переключаться между ними с помощью HTTP-заголовка Accept или просто изменив расширение с .xml на .json.

Имейте в виду, что как только мы начинаем говорить о поддержке XML, мы начинаем говорить о валидации, пространствах имен и т.д. Если этого не требует ваша отрасль, избегайте поддержки всех этих усложнений. По крайней мере, вначале. А если в этом функционале нет острой необходимости, то всегда. JSON является простым, лаконичным и функциональным. Сделайте так, чтобы ваш XML выглядел так же, если это возможно.

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

Обратите внимание, что JSON-Schema предлагает возможности по валидации XML, если вам все-таки нужен такой функционал.

Создавайте детальные ресурсы

Сначала гораздо проще создавать API, которые имитируют основной домен приложения или архитектуру базы данных вашей системы. В конце концов, вы захотите объединить сервисы, которые используют несколько основных ресурсов, чтобы избежать избыточности информации. Позже будет гораздо проще создать большие ресурсы из отдельных ресурсов, чем детальные ресурсы из более крупных составных ресурсов. Упростите себе задачу и начните с небольших, легко определяемых ресурсов, предоставив для них CRUD-функциональность. Ресурсы без лишней информации, ориентированные на конкретные ситуации, можно сделать позже.

Учитывайте связность

Одним из принципов REST является связность через ссылки. Хотя сервисы остаются полезными и без них, API становится более самоописательным, когда в ответе содержатся ссылки. По крайней мере, ссылка “на себя” информирует клиентов, как данные были или могут быть получены. Кроме того, используйте заголовок Location, который должен содержать ссылку на создание ресурса с помощью POST (или PUT). Для коллекций возвращайте в ответе сведения о том, что поддерживается пагинация, а также, как минимум, ссылки “первая”, “последняя”, “следующая” и “предыдущая”.

Что касается форматов ссылок, то их существует довольно много.

Спецификация HTTP веб-ссылок RFC5988 определяет ссылку следующим образом:

Ссылка — это типизированное соединение между двумя ресурсами, идентифицируемыми интернационализированными идентификаторами ресурсов (IRI) [RFC3987]

Ссылка состоит из:

• контекстного IRI
• типа ссылки
• целевого IRI
• целевых атрибутов (опционально)

Ссылку можно рассматривать как утверждение вида имеет ресурс в , который имеет .

По меньшей мере, размещайте ссылки в HTTP-заголовке Link, как это рекомендовано в спецификации, или используйте JSON-представление данного стиля HTTP-ссылок (например, ссылки в стиле Atom, см. RFC4287). По мере того, как ваш API будет становиться более зрелым, вы сможете использовать более сложные стили ссылок, такие как HAL+JSON, Siren, Collection+JSON и/или JSON-LD и т.д.

Данный сайт является переводом RestApiTutorial.com