Что такое rest

Что такое rest

Что такое REST?

• Определенно не HTTP
• Не протокол
• Не спецификация

Вот почему вокруг REST APIs так много споров.

И всё-таки.

REST это стиль архитектуры.

О, хорошо… но что такое стиль архитектуры?

Стиль архитектуры

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

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

REST выступает за представление состояния передачи

Это было записано Роем Филдингом в его докторской диссертации в 2000 году, где он описал существующую и современную веб-архитектуру как абстракцию.

Название было призвано вызывать представление о том, как ведет себя хорошо разработанное веб-приложение.

Рой описал REST на простом примере:

Рассмотрим сеть веб-страниц как виртуальную машину состояний.

Каждая страница представляет состояние:

1. Во-первых, пользователь получает первое состояние в виде индексного состояния.

2. Затем пользователь переходит через приложение, выбирая ссылку (здесь ссылка на страницу)

3. Результат передачи следующего состояния пользователю.

REST все еще не HTTP

Конечно, еще в 2000 году сеть уже работала на HTTP, и Рой со своими коллегами-инженерами много работали над этим.

Однако REST не определяет конкретные детали реализации системы и не определяет какой-либо синтаксис протокола.

Вполне возможно иметь архитектуру RESTful поверх протоколов, отличных от HTTP.

Например, CoAP (протокол ограниченного применения) является протоколом RESTful для встроенных устройств (Internet of Things) и предназначен для использования минимальных ресурсов как на устройстве, так и в сети.

Так зачем использовать REST?

Всемирная паутина основана на архитектуре REST.

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

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

Итак, когда это API RESTful?

API является RESTful, когда он постоянно действует под ограничениями REST.

REST определяет 6 ограничений для достижения желаемой оптимизации системы:

Это ограничение основано на принципе разделения интересов.

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

2. Без гражданства

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

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

Наиболее эффективным сетевым запросом является тот, который не использует сеть.

Когда мы создаем наш API, он не должен игнорировать кеширование.

4. Правильный интерфейс

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

4.1. Идентификация ресурсов

Это означает, что любая информация, которая может быть названа, может быть ресурсом (изображение, документ или даже набор других ресурсов)

4.2. Манипулирование ресурсами через представления

Ресурс может быть представлен различными способами.

Например, HTML, XML, JSON или даже JPEG-файл.

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

4.3 В-третьих, самоописательные сообщения

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

4.4. Hypermedia должна быть двигателем состояния приложения

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

Как вы можете видеть, многие из этих правил могут быть реализованы в протоколе HTTP. Поэтому, когда API использует HTTP правильно, это огромный шаг к тому, чтобы стать RESTful.

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

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

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

6. Код по требованию

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

Итак, как создать REST API?

Правильно использовать HTTP

Если вы строите RESTful API, используйте протокол RESTful. Для Интернета HTTP-протокол является определенным выбором. Создайте свой API, чтобы он правильно использовал HTTP.

Создайте единый интерфейс

Сопоставьте свои концепции с ресурсами и назначьте соответствующие идентификаторы для каждого из них. Простым примером может служить служба базы данных пользователей. В такой службе мы можем назвать два ресурса; Пользователей и пользователей (ресурс сбора). Эти ресурсы могут быть идентифицированы с URI / users и / user / URI вашего интерфейса API.

Управляйте своим API-гиперссылками

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

Что такое REST API

REST API это HTTP API (иногда говорят WEB API) построенный по принципам REST-архитектуры. Впервые термин REST ввел Рой Филдинг в своей докторской диссертации «Architectural Styles and the Design of Network-based Software Architectures» в 2000 году. Многие обратили на нее серьезное внимание, потому что Рой был не случайным человеком в индустрии. Этот ученый был одним из ключевых разработчиков протокола HTTP/1.0 и автором HTTP/1.1. Он участвовал в разработке языка HTML и стандарта URI. Кроме того, он со-автор некогда самого популярного веб-сервера в мире Apache Web Server.

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

• Немного истории
• Единообразие интерфейса
• Кэширование
• Отсутствие состояния
• Клиент-серверная архитектура
• Слои
• Код по требованию (необязательное ограничение)
• Преимущества REST
• По-простому
• JSONAPI
• Дополнительные материалы

Немного истории

Прежде чем обсуждать конкретно, что из себя представляют принципы REST, нужно немного поговорить о его истории. Глобально, REST это не про то как делать HTTP API. REST это, то по каким принципам должен был быть построен весь WEB.

Since 1994, the REST architectural style has been used to guide the design and development of the architecture for the modern Web. This work was done in conjunction with my authoring of the Internet standards for the Hypertext Transfer Protocol (HTTP) and Uniform Resource Identifiers (URI), the two specifications that define the generic interface used by all component interactions on the Web.

— Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures, p. 107.

То есть не REST появился для того чтобы упорядочить WEB, а WEB стал таким чтобы соответствовать REST.

Термин «REST» был введён Роем Филдингом, одним из создателей протокола «HTTP», лишь в 2000 году. В своей диссертации «Архитектурные стили и дизайн сетевых программных архитектур» («Architectural Styles and the Design of Network-based Software Architectures») в Калифорнийском университете в Ирвайне он подвёл теоретическую основу под способ взаимодействия клиентов и серверов во Всемирной паутине, абстрагировав его и назвав «передачей представительного состояния».

Чтобы протокол взаимодействия соответствовал REST-стилю, необходимо соблюсти, как минимум, 5 требований. Если сервис соблюдает только часть из них, то про такой протокол говорят, что он REST-like. Если соблюдаются все требования, то протокол является RESTful. На практике, есть ситуации, в которых невозможно следовать REST требованиям, поэтому большинство протоколов являются REST-like, даже если они утверждают другое.

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

1. Идентификация. В отличие от RPC, в котором протоколы ориентированы на действия, в REST стиле подразумевается ориентация на ресурсы (существительное). Взаимодействие с каждым ресурсом происходит посредством представлений ресурса, запрашиваемых по URN, который идентифицирует конкретный ресурс. То есть, мы никогда не взаимодействуем с самим ресурсом напрямую, а получаем лишь его представления, которых может быть много. Сервер может отдать данные в формате json или html, хотя при этом ни один из них не является реальным типом хранения внутри сервера.
2. Манипуляция ресурсами через представление. Если клиент хранит представление ресурса, включая метаданные — он имеет достаточно данных для модификации или удаления ресурса.
3. «Самоописываемые» сообщения. Каждое сообщение содержит достаточно информации, чтобы описать, каким образом его обрабатывать. К примеру, какой парсер необходимо применить для извлечения данных, может быть описано в Internet медиа-типе, другими словами, посылая на сервер json в теле http запроса, REST диктует обязательную установку типа контента в заголовке. В общем случае для обработки сообщения должно быть достаточно информации из самого сообщения (всё, что может передаваться по http).

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

Метод	Маршрут	Описание
GET	/photos	display a list of all photos
GET	/photos/new	return an HTML form for creating a new photo
POST	/photos	create a new photo
GET	/photos/:id	display a specific photo
GET	/photos/:id/edit	return an HTML form for editing a photo
PATCH/PUT	/photos/:id	update a specific photo
DELETE	/photos/:id	delete a specific photo

Кэширование

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

Отсутствие состояния

Протокол взаимодействия между клиентом и сервером не сохраняет какого-либо сессионного состояния после запроса и ответа (Stateless protocol). В случае необходимости, такое состояние должно сохраняться на клиенте. Только тогда пользователь отвязан от конкретного сервера, что, в свою очередь, позволяет масштабироваться и безболезненно переносить (балансировать) запросы между серверами.

Примером такого состояния является корзина в интернет магазине. Если она привязана к пользовательской сессии и хранится на конкретном сервере (а не в браузере клиента), то отправить запрос пользователя на другой сервер станет невозможно. Он просто не увидит своей корзины. Эту проблему можно решить двумя способами. Первый — хранить её на клиенте, используя, например, cookie. Вторая — изменением способа хранения корзины на сервере и помещением её в базу данных, которая доступна со всех серверов.

На практике сайты активно используют понятие «сессии», при котором данные могут храниться на стороне сервера, что является нарушением REST.

Клиент-серверная архитектура

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

Слои

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

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

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

Преимущества REST

Филдинг указывал, что приложения, не соответствующие приведённым условиям, не могут называться REST-приложениями. Если же все условия соблюдены, то, по его мнению, приложение получит следующие преимущества:

• Надёжность (за счёт отсутствия необходимости сохранять информацию о состоянии клиента, которая может быть утеряна)
• Производительность (за счёт использования кэша)
• Масштабируемость
• Прозрачность системы взаимодействия (особенно необходимая для приложений обслуживания сети)
• Простота интерфейсов
• Портативность компонентов
• Лёгкость внесения изменений
• Способность эволюционировать, приспосабливаясь к новым требованиям (на примере Всемирной паутины)

По-простому

Грубо говоря, REST это набор рекомендаций о том, как лучше сделать для получения преимуществ, описанных абзацем выше. Чем больше рекомендаций вы выполните, тем более REST получается приложение. А поскольку жизнь сложна, то это нормально, что REST ориентированными сервисы являются только отчасти. Использования REST как догмы ни к чему хорошему не приведёт. И REST никоим образом не заменяет собой RPC. Выбор решения зависит от ситуации и предъявляемых требований.

JSONAPI

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

Есть и другой путь. В 2013 году появился стандарт под названием jsonapi, в котором очень подробно описано как создавать REST -like сервисы. Для его реализации написано множество библиотек под все популярные языки программирования. Как минимум, я рекомендую с ним ознакомиться, а ещё лучше — взять на вооружение. Использование открытых стандартов в промышленном программировании делает нашу жизнь проще, бизнес богаче, а волосы шелковистее.

Дополнительные материалы

• Руководство по созданию RESTful-сервиса
• Architectural Styles and the Design of Network-based Software Architectures
• Zalando RESTful API and Event Guidelines
• Почему никто не понимает REST

Что такое REST?

Архитектура REST описывается шестью ограничениями. Эти ограничения, применительно к архитектуре, первоначально были представлены Роем Филдингом (Roy Fielding) в его докторской диссертации и определяют основы RESTful стиля.

Шесть ограничений:

Единый интерфейс (Uniform Interface)

Единый интерфейс определяет интерфейс между клиентами и серверами. Это упрощает и отделяет архитектуру, которая позволяет каждой части развиваться самостоятельно. Четыре принципа единого интерфейса:

Основан на ресурсах

Отдельные ресурсы определяются в запросе, для чего используется URI, как идентификаторы ресурсов. Сами ресурсы концептуально отделены от представлений, которые возвращаются клиенту. Например, сервер не отправляет свою базу данных, а, скорее, некоторые HTML, XML или JSON, которые представляет некоторые записи в базе данных, например, на финском языке и в UTF-8, в зависимости от деталей запроса и реализации сервера.

Манипуляции над ресурсами через представления

Когда пользователь имеет представление о ресурсе, в том числе о связанных метаданных, он имеет достаточно информации для изменения или удаления ресурса на сервере, если у него есть на это разрешение

Самодокументируемые сообщения

Каждое сообщение содержит достаточно информации для описания того, как его выполнить. Например, вызываемый парсер может описываться с помощью Internet media type (так же известным как MIME) Ответы также явно указывают на их способность кешировать.

Hypermedia as the Engine of Application State (HATEOAS)

Клиенты предоставляют статус через содержимое body, параметры строки запроса, заголовки запросов и запрашиваемый URI (имя ресурса). Это называется гипермедиа (или гиперссылки с гипертекстом)

Наряду с приведенным выше описанием, HATEOAS также означает, что, в случае необходимости ссылки содержатся в теле ответа (или заголовках) для поддержки URI извлечения самого объекта или запрошенных объектов. Позднее, мы затронем эту тему глубже.

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

Отсутствие состояний (Stateless)

Так как REST это акроним для REpresentational State Transfer, отсутствие состояний является важной чертой. Таким образом, это значит, что необходимое состояние для обработки запроса содержится в самом запросе, либо в рамках URI, параметрах строки запроса, тела или заголовках. URI уникально идентифицирует ресурс, и тело содержит состояние (или изменение состояния) этого ресурса. Затем, после того, как сервер завершит обработку, состояние или его часть(и) отдаётся обратно клиенту через заголовки, статус и тело ответа.

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

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

Каждый встречал проблему с кнопкой «Назад» в своём веб приложении, когда оно ведет себя по-разному в одной точке, потому что ожидались действия в определенном порядке? Такое происходит, когда нарушен принцип отсутствия состояний. Есть случаи, когда не соблюдается принцип отсутствия состояний, например, three-legged OAuth, ограничение скорости вызова API и т.д. Однако, приложите максимум усилий, чтобы состояние приложения не занимало несколько запросов к вашему сервису.

Кеширование ответа (Cacheable)

Как и в World Wide Web, клиент может кэшировать ответы. Таким образом, ответы явно или неявно определяют себя как кешируемые или нет, для предотвращения повторного использования клиентами устаревших или некорректных данных в ответ на дальнейшие запросы. Хорошо спроектированное кэширование частично или полностью устраняет некоторые клиент-серверные взаимодействия, способствуя дальнейшей масштабируемости и производительности.

Клиент-сервер (Client-Server)

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

Многоуровневая система (Layered System)

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

«Код по требованию» (Code on Demand — опционально)

Серверы могут временно расширять или настраивать функциональность клиента, передавая ему логику, которую он может исполнять. Например, это могут быть скомпилированные Java-апплеты или клиентские скрипты на Javascript

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

Замечание Единственным необязательным ограничением для RESTful архитектуры — это «код по требованию». Если сервис не проходит по любым другим условиям, то его совершенно точно нельзя назвать RESTful.

Что такое REST API?

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

Что такое API

В общем, API (Application Programming Interface) обеспечивает взаимодействие между двумя системами. Это как винтик, связывающий две детали, или как шестеренка, при помощи которой приводятся в движение две соседние шестеренки (как на картинке ниже).

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

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

В конечном счете, разработчики вызывают API незримо для пользователя для извлечения информации в свои приложения. Кнопка в графическом интерфейсе пользователя программно подключена для вызова внешних служб. Например, кнопки Twitter или Facebook, которые взаимодействуют с социальными сетями, или видео Youtube, которые извлекают видео с youtube.com, работают под управлением веб-API.

API, использующие протокол HTTP = веб-сервисы

«Веб-сервис» — это веб-приложение, предоставляющее ресурсы в формате, используемом другими компьютерами. Веб-сервисы включают в себя различные типы API, в том числе REST и SOAP API. Веб-сервисы — это, в основном, запросы и ответы между клиентами и серверами (компьютер запрашивает ресурс, а веб-сервис отвечает на запрос).

API, использующие протокол HTTP для передачи запросов и ответов, рассматриваются как «веб-сервисы». В случае веб-сервисов клиент, делающий запрос на ресурс, и сервер API, предоставляющий ответ, могут использовать любой язык программирования или платформу. Не имеет значения, какой ЯП или платформа будут использоваться, потому что запрос сообщения и ответ сделаны через общий веб-протокол HTTP.

Веб-протокол является частью прекрасного веб-сервисов: они независимы от языка и поэтому совместимы между различными платформами и системами. При документировании REST API не имеет значения, строят ли инженеры API с помощью Java, Ruby, Python или какого-либо другого языка. Запросы выполняются через HTTP, и ответы возвращаются через HTTP.

Диаграмма ниже показывает общую модель REST API:

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

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

API-интерфейсы SOAP являются предшественниками REST API

До того, как REST стал самым популярным веб-сервисом, SOAP (Simple Object Access Protocol) был гораздо более распространенным. Чтобы лучше понять REST, полезно иметь некоторое понимание SOAP. Заодно и увидеть, что отличает SOAP и REST.

SOAP — это стандартизированный протокол, который требует XML в качестве формата сообщений для запросов и ответов. Как стандартный протокол, формат сообщения обычно определяется с помощью файла WSDL (язык описания веб-служб).

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

Сообщения SOAP заключены в «конверт», который включает в себя заголовок и тело, используя определенную схему XML и пространство имен. Пример формата запроса и ответа SOAP см. SOAP против REST 101: понимание различий.

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

SOAP по-прежнему используется в enterprise приложениях (особенно в финансовых учреждениях) со связью server-to-server, но в последние годы SOAP вымещается REST, особенно для API открытых сетей.

REST — стиль, а не стандарт

Как и SOAP, REST (Representational State Transfer) использует HTTP в качестве протокола передачи данных для запросов и ответов. Однако, в отличие от SOAP, REST является архитектурным стилем, а не стандартным протоколом. Вот почему REST API иногда называют RESTful API — REST — это общий стиль, которому следует API.

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

В архитектурном стиле нет ограничений XML в качестве формата сообщения. API REST могут использовать любой формат сообщений, который хотят использовать разработчики API, включая XML, JSON, Atom, RSS, CSV, HTML и другие.

Несмотря на разнообразие параметров формата сообщений, большинство API REST используют JSON (нотацию объектов JavaScript) в качестве формата сообщений по умолчанию. Они используют JSON, потому что он обеспечивает легкий, простой и более гибкий формат сообщений, который увеличивает скорость связи. Облегченная природа JSON также позволяет выполнять сценарии мобильной разработки и легок для парсинга в Интернете с помощью JavaScript.

Напротив, в XML, XSLT больше используется для представления или, скорее, «преобразования» («T» в XSLT) содержимого, хранящегося на языке XML. XSLT обеспечивает удобочитаемость (а не обработку данных, хранящихся в формате XML).

REST фокусируется на ресурсах, доступ к которым осуществляется через URL

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

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

Вот пример, как выглядит конечная точка:

http://apiserver.com/homes?limit=5&format=json 

Конечная точка показывает весь путь к ресурсу. Однако в документации вы обычно разделяете этот URL на более конкретные части:

• Базовый путь (базовый URL или хост) относится к общему пути для API. В приведенном выше примере базовый путь — http://apiserver.com;
• Отношение конечной точки к конечному пути этой точки. В приведенном примере это /homes ;
• ?limit=5&format=json часть конечной точки содержит параметры строки запроса для этой точки.

В приведенном выше примере конечная точка получит ресурс «homes» и ограничит результат до 5 домов. Будет возвращен ответ в формате JSON.

Можно иметь несколько конечных точек, которые ссылаются на один и тот же ресурс. Вот один из вариантов:

http://apiserver.com/homes/

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

Tip: Отношения между ресурсами и методами часто описывается в терминах «существительные» и «глаголы». Ресурс — это существительное, потому что это объект или вещь. Глагол — это то, что вы делаете с этим существительным. Объединяя существительные с глаголами, вы формируете язык REST.

Более подробно рассмотрим конечные точки в следующих разделах (например, в Обзоре руководства описания API мы рассмотрим каждое свойство ресурса). А здесь дан краткий обзор.

Сама сеть следует за REST

Термины «запросы GET» и «ответы на сообщения», передаваемые по «протоколу HTTP», могут показаться незнакомыми, но это всего лишь официальная терминология REST для описания происходящего. Поскольку мы используем Интернет, мы уже знакомы с тем, как работают API-интерфейсы REST — сама сеть по сути следует стилю RESTful.

Когда мы открываем браузер и переходим на https://idratherbewriting.com, в действительности мы используем протокол HTTP ( http: // ) для отправки запроса GET на ресурс, доступный на веб-сервере. Ответ от сервера отправляет контент с этого ресурса обратно по протоколу HTTP. Наш браузер — это просто клиент, который делает ответ на сообщение читаемым и знакомым нашему глазу.

Можно увидеть этот ответ в curl, если открыть окно терминала и набрать curl https://idratherbewriting.com. (Предполагается, что curl установлен )

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

API REST не сохраняют состояния запроса, но ответы могут кэшироваться

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

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

Кэширование API REST аналогично кешированию веб-страниц. Браузер использует значение времени последнего изменения в заголовках HTTP, чтобы определить, нужно ли ему снова получать ресурс. Если содержимое не было изменено с момента последнего извлечения, вместо него можно использовать кэшированную копию. Кэширование увеличивает скорость ответа.

API REST имеют и другие характеристики, о которых можно узнать побольше в этом видео. Одна из таких характеристик включает ссылки в ответах, позволяющие пользователям переходить к дополнительным элементам. Эта функция называется HATEOS, или Hypermedia As The Engine of State.

Изучение подробной теории REST не является целью курса, также, как и незнание подробной теории не станет проблемой документирования REST API. Тем не менее, существует множество технических книг, курсов и веб-сайтов, в которых более подробно рассматриваются концепции, ограничения и архитектура REST API, к которым при желании можно обращаться. Например, посмотрите «Основы программирования: веб-сервисы» Дэвида Гасснера на lynda.com.

API REST не используют файлы WSDL, но некоторые спецификации все же существуют

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

Хотя и существует возможный файл WADL (Web Application Description Language), который можно использовать для описания API-интерфейсов REST, им используются редко, поскольку там неадекватно описываются все ресурсы, параметры, форматы сообщений и другие атрибуты API-интерфейса REST. , (Помните, что REST API — это архитектурный стиль, а не стандартизированный протокол.)

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

Некоторые формальные спецификации — например, OpenAPI и RAML — были разработаны для описания API REST. Когда вы описываете свой API с использованием спецификации OpenAPI или RAML, инструменты, которые могут читать эти спецификации (например, Swagger UI или консоль RAML API), будут генерировать вывод интерактивной документации.

Спецификация OpenAPI может заменить файл WSDL, более распространенный в SOAP. Такие инструменты, как Swagger UI, которые читают документы спецификаций, обычно создают интерактивную документацию (с использованием API-консолей или API-проводников) и позволяют вам тестировать вызовы REST и просматривать ответы прямо в браузере.

Но не ожидайте, что выходные данные документации Swagger UI или RAML API Console будут содержать все детали, которые потребуются пользователям для работы с вашим API. Например, эти выходные данные не будут включать информацию о ключах авторизации, подробностях о рабочих процессах и взаимозависимостях между конечными точками и так далее. Вывод Swagger или RAML обычно содержит только адресную документацию, на которую обычно приходится только треть или половина всей необходимой документации (в зависимости от API).

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