Введение в REST API — RESTful веб-сервисы
Эта статья начинает серию постов о разработке REST API:
Intro to RESTful Web Services
REST означает REpresentational State Transfer (Википедия: «передача состояния представления»). Это популярный архитектурный подход для создания API в современном мире.
Вы изучите:
Что такое REST?
REST расшифровывается как REpresentational State Transfer. Это был термин, первоначально введен Роем Филдингом (Roy Fielding), который также был одним из создателей протокола HTTP. Отличительной особенностью сервисов REST является то, что они позволяют наилучшим образом использовать протокол HTTP. Теперь давайте кратко рассмотрим 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 — универсальный идентификатор ресурса. Например:
REST и Ресурсы
Важно отметить, что с REST вам нужно думать о приложении с точки зрения ресурсов:
Определите, какие ресурсы вы хотите открыть для внешнего мира
Используйте глаголы, уже определенные протоколом HTTP, для выполнения операций с этими ресурсами.
Вот как обычно реализуется служба REST:
Компоненты HTTP
HTTP определяет следующую структуру запроса:
Методы HTTP-запроса
Метод, используемый в HTTP-запросе, указывает, какое действие вы хотите выполнить с этим запросом. Важные примеры:
Код статуса ответа HTTP
Код состояния всегда присутствует в ответе HTTP. Типичные примеры:
Резюме
В статье приведен на верхнем уровне обзор архитектурного стиля REST. Подчеркивается тот факт, что HTTP является основным строительным блоком REST сервисов. HTTP — это протокол, который используется для определения структуры запросов и ответов браузера. Мы видели, что HTTP имеет дело главным образом с ресурсами, доступными на веб-серверах. Ресурсы идентифицируются с помощью URI, а операции над этими ресурсами выполняются с использованием глаголов, определенных протоколом HTTP.
Наконец, мы рассмотрели, как службы REST наилучшим образом используют функции, предлагаемые HTTP, для предоставления ресурсов внешнему миру. 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-сервис.
Основы REST: теория и практика
Авторизуйтесь
Основы REST: теория и практика
REST, Representational State Transfer, является архитектурным стилем для обеспечения стандартов между компьютерными системами в сети, что облегчает для систем обмен данными друг с другом. Системы, отвечающие требованиям REST и часто называемые RESTful, характеризуются тем, что не имеют сохранения состояния и разделяют интересы клиента и сервера. Мы рассмотрим, что означают эти термины и почему они являются полезными для услуг в Интернете.
Разделение клиента и сервера
В архитектурном стиле REST реализация клиента и реализация сервера могут быть выполнены независимо друг от друга. Это означает, что код на стороне клиента может быть изменён в любое время без ущерба для работы сервера, а код на стороне сервера может быть изменён без влияния на работу клиента.
До тех пор, пока каждая сторона знает, какой формат сообщений следует направлять другой стороне, они могут храниться модульно и раздельно. Отделяя задачи пользовательского интерфейса от задач хранения данных, мы повышаем гибкость интерфейса между платформами и улучшаем расширяемость за счёт упрощения компонентов сервера. Кроме того, разделение позволяет каждому компоненту развиваться независимо.
Используя интерфейс REST, различные клиенты попадают в одни и те же конечные точки REST, выполняют те же действия и получают одинаковые ответы.
Отсутствие сохранения состояния
Системы, которые следуют парадигме REST, не имеют сохранения состояния, что означает, что серверу не нужно знать о состоянии клиента и наоборот. Таким образом, и сервер, и клиент могут понять любое полученное сообщение, даже не увидев предыдущих сообщений. Это отсутствие сохранения состояния обеспечивается за счёт использования ресурсов, а не команд. Они описывают любые объекты, документы или вещи, которые могут потребоваться для хранения или отправки в другие службы.
25–27 ноября, Онлайн, Беcплатно
Эти ограничения помогают RESTful-приложениям достигать надёжности, быстрой производительности и расширяемости, как компонентам, которые могут быть управляемы, обновлены и повторно использованы, не затрагивая систему в целом даже во время её работы.
Теперь мы изучим, как на самом деле происходит взаимодействие между клиентом и сервером, когда мы внедряем RESTful-интерфейс.
Взаимодействие между клиентом и сервером
В архитектуре REST клиенты отправляют запросы на поиск или изменение ресурсов, а серверы отправляют ответы на эти запросы. Давайте рассмотрим стандартные способы направления запросов и ответов.
Отправка запросов
REST требует, чтобы клиент сделал запрос на сервер для получения или изменения данных на сервере. Запрос обычно состоит из:
Существует 4 основных метода НТТР, которые мы используем в запросах для взаимодействия с ресурсами в системе REST:
В заголовке запроса клиент отправляет тип контента, который он может получить с сервера. Это поле называется Accept. Оно обеспечивает, что сервер не посылает данные, которые не могут быть поняты или обработаны клиентом. Параметры типов контента — это типы MIME (или Multipurpose Internet Mail Extensions, о которых вы можете прочитать больше в MDN Web Docs).
Типы MIME, используемые для указания типов контента в поле Accept, состоят из типа и подтипа. Они разделены слэшем (/).
Другие типы и часто используемые подтипы:
Например, клиент, имеющий доступ к ресурсу с идентификатором 123 в ресурсе статей на сервере, может отправить запрос GET следующим образом:
Запросы должны содержать путь к ресурсу, на котором должна выполняться операция. В RESTful API пути должны быть разработаны так, чтобы помочь клиенту понять, что происходит. Обычно первая часть пути должна быть множественной формой ресурса. Это позволяет легко читать и понимать вложенные пути.
Пути должны содержать информацию, необходимую для определения местоположения ресурса с необходимой степенью конкретности. При ссылке на список или коллекцию ресурсов не всегда необходимо добавлять идентификатор. Например, запрос POST на путь somesite.com/persons не будет нуждаться в дополнительном идентификаторе, так как сервер генерирует идентификатор для нового объекта.
В тех случаях, когда сервер отправляет клиенту полезную нагрузку, он должен включать тип контента в заголовок ответа. Это поле заголовка контента предупреждает клиента о типе данных, которые он посылает в теле ответа. Эти типы контента являются типами MIME, точно так же, как они находятся в поле Accept заголовка запроса. Тип контента, который сервер возвращает обратно в ответе, должен быть одним из параметров, указанных клиентом в поле принятия запроса.
Например, клиент получает доступ к ресурсу с идентификатором 123 в разделе статей с этим запросом GET:
Сервер должен отправить обратно контент с заголовком ответа:
Это означает, что запрашиваемый контент возвращается в тело ответа с text/html — типом контента, который клиент будет в состоянии принять.
Коды ответов
Ответы от сервера содержат коды состояния для оповещения клиента об успехе операции. Как разработчику вам не нужно знать каждый код состояния (их много), но вы должны знать самые распространённые и то, как они используются.
Для каждого метода НТТР ожидаются коды статуса, которые сервер должен вернуть в случае успеха:
Если операция не работает, вернётся наиболее конкретный код состояния, соответствующий возникшей проблеме.
Предположим, у нас есть приложение, которое позволяет вам просматривать, создавать, редактировать и удалять клиентов и заказы для небольшого магазина одежды, размещённого на сайте fashionboutique.com. Мы можем создать НТТР API, который позволит клиенту выполнять следующие функции.
Если бы мы хотели увидеть всех клиентов, запрос выглядел бы так:
Возможный заголовок ответа будет выглядеть следующим образом:
Создание нового клиента путем размещения данных:
Затем сервер генерирует идентификатор этого объекта и возвращает его клиенту с таким заголовком:
Для просмотра одного клиента мы используем метод GET, указывая идентификатор этого клиента:
Возможный заголовок ответа будет выглядеть следующим образом:
Мы можем обновить этого клиента, вставив новые данные с помощью метода PUT:
Мы также можем УДАЛИТЬ этого клиента, указав его идентификатор:
Практика с REST
Давайте представим, что мы создаём сайт для сбора фотографий. Мы хотим сделать API, чтобы отслеживать пользователей, места проведения и фотографии этих мест. Этот сайт имеет index.html и style.css. Каждый пользователь имеет имя пользователя и пароль. Каждая фотография имеет место проведения и владельца (т.е. пользователя, который сделал фотографию). Каждое место имеет название и адрес. Можете ли вы разработать систему REST, которая будет учитывать:
Для начала опишите:
REST API
REST API — это способ взаимодействия сайтов и веб-приложений с сервером. Его также называют RESTful.
Термин состоит из двух аббревиатур. API (Application Programming Interface) — это код, который позволяет двум приложениям обмениваться данными с сервера. На русском языке его принято называть программным интерфейсом приложения. REST (Representational State Transfer) — это способ создания API с помощью протокола HTTP. На русском его называют «передачей состояния представления».
REST API применяют везде, где пользователю сайта или веб-приложения нужно предоставить данные с сервера. Например, при нажатии иконки с видео на видеохостинге REST API проводит операции и запускает ролик с сервера в браузере. В настоящее время это самый распространенный способ организации API. Он вытеснил ранее популярные способы SOAP и WSDL.
У RESTful нет единого стандарта работы: его называют «архитектурным стилем» для операций по работе с серверов. Такой подход в 2000 году в своей диссертации ввел программист и исследователь Рой Филдинг, один из создателей протокола HTTP.
Принципы REST API
У RESTful есть семь принципов написания кода интерфейсов.
Отделения клиента от сервера (Client-Server). Клиент — это пользовательский интерфейс сайта или приложения, например, поисковая строка видеохостинга. В REST API код запросов остается на стороне клиента, а код для доступа к данным — на стороне сервера. Это упрощает организацию API, позволяет легко переносить пользовательский интерфейс на другую платформу и дает возможность лучше масштабировать серверное хранение данных.
Отсутствие записи состояния клиента (Stateless). Сервер не должен хранить информацию о состоянии (проведенных операций) клиента. Каждый запрос от клиента должен содержать только ту информацию, которая нужна для получения данных от сервера.
Кэшируемость (Casheable). В данных запроса должно быть указано, нужно ли кэшировать данные (сохранять в специальном буфере для частых запросов). Если такое указание есть, клиент получит право обращаться к этому буферу при необходимости.
Единство интерфейса (Uniform Interface). Все данные должны запрашиваться через один URL-адрес стандартными протоколами, например, HTTP. Это упрощает архитектуру сайта или приложения и делает взаимодействие с сервером понятнее.
Многоуровневость системы (Layered System). В RESTful сервера могут располагаться на разных уровнях, при этом каждый сервер взаимодействует только с ближайшими уровнями и не связан запросами с другими.
Предоставление кода по запросу (Code on Demand). Серверы могут отправлять клиенту код (например, скрипт для запуска видео). Так общий код приложения или сайта становится сложнее только при необходимости.
Начало от нуля (Starting with the Null Style). Клиент знает только одну точку входа на сервер. Дальнейшие возможности по взаимодействию обеспечиваются сервером.
Начните свой путь в IT
Освойте разработку, аналитику данных, Data Science или другие востребованные профессии — получите все курсы для входа в IT по цене одного.
Стандарты
Сам по себе RESTful не является стандартом или протоколом. Разработчики руководствуются принципами REST API для создания эффективной работы с серверов для своих сайтов и приложений. Принципы позволяют выстраивать серверную архитектуру с помощью других протоколов: HTTP, URL, JSON и XML.
Это отличает REST API от метода простого протокола доступа к объектам SOAP (Simple Object Access Protocol), созданного Microsoft в 1998 году. В SOAP взаимодействие по каждому протоколу нужно прописывать отдельно только в формате XML. Также в SOAP нет кэшируемости запросов, более объемная документация и реализация словаря, отдельного от HTTP. Это делает стиль REST API более легким в реализации, чем стандарт SOAP.
Несмотря на отсутствие стандартов, при создании REST API есть общепринятые лучшие практики, например:
Архитектура
REST API основывается на протоколе передачи гипертекста HTTP (Hypertext Transfer Protocol). Это стандартный протокол в интернете, созданный для передачи гипертекста. Сейчас с помощью HTTP отправляют любые другие типы данных.
Каждый объект на сервере в HTTP имеет свой уникальный URL-адрес в строгом последовательном формате. Например, второй модуль обучающего видео про Python будет храниться на сервере по адресу http://school.ru/python/2.
В REST API есть четыре метода HTTP, которые используют для действий с объектами на серверах:
Такие запросы еще называют идентификаторами CRUD: create (создать), read (прочесть), update (обновить) delete (удалить). Это стандартный набор действий для работы с данными. Например, чтобы обновить видео про Python по адресу http://school.ru/python/2 REST API будет использовать метод PUT, а для его удаления — DELETE.
В каждом HTTP-запросе есть заголовок, за которым следует описание объекта на сервере — это и есть его состояние.
Как работает RESTful
Например, на сайте отеля есть система бронирования номеров трех типов: эконом, стандарт и люкс. В REST API каждому типу будет присвоен свой URL на странице бронирования:
Такие URL однозначно определяют ресурс на сервисе — данные о доступных номерах каждого класса. Чтобы взаимодействовать с этими ресурсам REST API применяет CRUD-команды протокола HTTP. Например, GET econom для передачи клиенту информации о номерах класса эконом. В RESTful такие запросы будут кэшироваться — клиенту не нужно обращаться к серверу снова при повторном запросе.
Также такая архитектура позволяет расставить приоритеты в обслуживании. Например, использование более производительных серверов для запросов на номера класса люкс. Такую архитектуру легко масштабировать: при появлении новых классов номеров, система будет обращаться напрямуя к ресурсам по новым URL.
Где применяют
REST API рекомендуют использовать в следующих случаях:
REST API используют чаще альтернативных методов, например SOAP. Помимо сайтов и веб-приложений RESTful используют для облачных вычислений.
Пример
Например, REST API используется в социальной сети Twitter. Запросы отправляются в формате JSON. Разработчики сторонних приложений могут использовать данные Twitter с помощью REST-запросов. Например:
GET geo/id/:place_id
Возвращает информацию о местоположении пользователей.
GET geo/reverse_geocode
Возвращает до 20 возможных местоположений по заданным координатам.
GET geo/search
Возвращает местоположения, которые могут быть прикреплены к твитам.
Что такое 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, использующие протокол HTTP для передачи запросов и ответов, рассматриваются как «веб-сервисы». В случае веб-сервисов клиент, делающий запрос на ресурс, и сервер API, предоставляющий ответ, могут использовать любой язык программирования или платформу. Не имеет значения, какой ЯП или платформа будут использоваться, потому что запрос сообщения и ответ сделаны через общий веб-протокол HTTP.
Веб-протокол является частью прекрасного веб-сервисов: они независимы от языка и поэтому совместимы между различными платформами и системами. При документировании REST API не имеет значения, строят ли инженеры API с помощью Java, Ruby, Python или какого-либо другого языка. Запросы выполняются через HTTP, и ответы возвращаются через HTTP.
Диаграмма ниже показывает общую модель REST API:
Любой язык программирования, создающий запрос, будет по-своему отправлять веб-запрос и анализировать ответ на своем языке. Эти специфичные для языка функции отправки запросов и анализа ответов не являются частью REST API (хотя они могут быть предоставлены в прилагаемом SDK). REST API не зависит от языка и обрабатывает входящую и исходящую информацию по HTTP.
API-интерфейсы SOAP являются предшественниками REST API
До того, как REST стал самым популярным веб-сервисом, SOAP (Simple Object Access Protocol) был гораздо более распространенным. Чтобы лучше понять REST, полезно иметь некоторое понимание SOAP. Заодно и увидеть, что отличает SOAP и REST.
Файл WSDL определяет разрешенные элементы и атрибуты в обмениваемых сообщениях. Файл WSDL является машиночитаемым и используется серверами, взаимодействующими друг с другом для облегчения связи.
Сообщения SOAP заключены в «конверт», который включает в себя заголовок и тело, используя определенную схему XML и пространство имен. Пример формата запроса и ответа SOAP см. SOAP против REST 101: понимание различий.
Основная проблема с SOAP заключается в том, что формат сообщений XML слишком многословный и тяжелый. Особенно это проблематично в мобильных сценариях, где размер файла и пропускная способность играют решающее значение. Многословный формат сообщения замедляет время обработки, что делает взаимодействия SOAP вялым.
SOAP по-прежнему используется в enterprise приложениях (особенно в финансовых учреждениях) со связью server-to-server, но в последние годы SOAP вымещается 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 экземпляров ресурса.
Вот пример, как выглядит конечная точка:
Конечная точка показывает весь путь к ресурсу. Однако в документации вы обычно разделяете этот URL на более конкретные части:
В приведенном выше примере конечная точка получит ресурс «homes» и ограничит результат до 5 домов. Будет возвращен ответ в формате JSON.
Можно иметь несколько конечных точек, которые ссылаются на один и тот же ресурс. Вот один из вариантов:
Приведенный выше URL-адрес может быть конечной точкой, которая извлекает домашний ресурс, содержащий определенный идентификатор. То, что передается обратно с сервера на клиент, является «представлением» ресурса. Ресурс может иметь много разных представлений (показывая все дома или дома, которые соответствуют определенным критериям, или дома в определенном формате и т.д.), Но здесь мы хотим видеть дом с определенным идентификатором.
Более подробно рассмотрим конечные точки в следующих разделах (например, в Обзоре руководства описания API мы рассмотрим каждое свойство ресурса). А здесь дан краткий обзор.
Сама сеть следует за REST
Можно увидеть этот ответ в 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 для описания элементов и параметров, разрешенных в запросах и ответах.
Чтобы понять, как взаимодействовать с REST API, нужно прочитать документацию по API. Необходимость читать документы делает роль технического писателя чрезвычайно важной для документирования 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 лежит запрос и ответ, передаваемые через Интернет.