Rest api для чего используется
Что такое 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 лежит запрос и ответ, передаваемые через Интернет.
REST API: минимум, который нужно знать новичку
Что такое программный интерфейс приложения (API)
Перед тем, как начать разговор о REST API, давайте вспомним, что такое API и для чего он нужен. API расшифровывается как Application Program Interface — программный интерфейс приложения. Данное понятие применимо не только к веб-разработке, но и к любым программным продуктам вообще. Наушники, микроволновые печи, телевизоры, микропроцессоры — все они имеют свой API.
Предположим, мы имеем дело с двумя такими совершенно разными разработками, каждая из которых обладает своим собственным API. Эти системы должны как-то взаимодействовать между собой, но есть некоторая сложность — ведь каждая из систем разработана на своем языке, по своим стандартам, со своими драйверами, на своей операционной системе и так далее. Чтобы как-то привести эти системы к общему знаменателю и иметь возможность коммуникации, мы используем API как некие внешние рычаги, которые влияют на внутреннее состояние каждой из систем. По этому принципу работает огромное количество проектов.
REST API — частный случай API
Допустим, мы написали сайт на PHP (Python, Java — не принципиально). PHP генерирует контент на сервере и по сети нам отправляет обратно уже сгенерированный HTML, JavaScript и CSS. Создавая сайт на PHP, вы получили некую статику, напрямую связывая код PHP, стили, HTML. Он взаимодействует с базой данных и выводит данные в шаблон. Предположим, мы задались целью разработать мобильное приложение под данную систему. Мобильное приложение должно работать с той же базой данных и мы должны как-то присоединить его к уже существующей системе.
Раньше многие шли по такому пути — создавали API для системы «сайт плюс база данных», и мобильное приложение работало через API или непосредственно через сам сайт. Но поддерживать и расширять такую концепцию было неудобно, поэтому постепенно перешли к варианту, когда используется связка backend и frontend. Backend по-прежнему работает с базой данных, а frontend является вообще отдельным приложением, которое, грубо говоря, ничего не знает про backend. Frontend является абстрагированный клиентом и может быть написан на Angular, React, Vue или просто на JavaScript.
Если для сайта имеется мобильное приложение, оно также относится к разряду клиентов и общается с backend-частью посредством API. При такой схеме клиентов может быть сколько угодно — мобильный клиент для Android, приложение под iOS, десктопное приложение, админка сайта и т. д. Частным случаем такой организации является REST API (Representational State Transfer) — некий стандартизированный протокол, позволяющий перемещать state и обмениваться им по API. Впервые его описал в своей диссертации Рой Филдинг. В ней он предложил соединять разные части программы либо сервисы по HTTP.
Критерии RESTful-приложения
Rest — это обычный запрос клиент-сервер с использованием HTTP протокола. В роли клиента не обязательно выступает браузер, это может быть мобильное приложение, десктопное приложение или же другой веб-сайт. В качестве ответа сервер выдает не привычную html-страницу, а просто набор данных, оформленных в том или ином формате. Чаще всего это JSON или XML. Неразрывно с REST следует AJAX (Asynchronous Javascript and XML).
Речь идет об отправке с браузера асинхронных запросов к серверу с помощью JavaScript. XML в данном случае не актуален, а процесс асинхронного общения браузера и веб-сервера задается именно REST-правилами. Веб-сервисы, которые полностью соответствуют парадигме Representational State Transfer, обычно называются RESTful. Чтобы приложение было RESTful, оно должно удовлетворять следующим правилам:
SOAP API — стандарт–предшественник REST API
Хотя на REST API и накладываются эти ограничения, он считается более простым в использовании, чем предшествующий ему протокол SOAP (простой протокол доступа к объектам). Последний выдвигает определенные требования, такие как обмен сообщениями XML, а также встроенные средства безопасности и соответствия транзакциям, что делает его медленнее и тяжеловеснее.
При отправке запроса данных в SOAP API, данные могут обрабатываться через любой из протоколов прикладного уровня: HTTP (для веб-браузеров), SMTP (для электронной почты), TCP и прочие. SOAP использует HTTP как транспортный протокол, в то время как REST базируется на нем. Как только запрос получен, возвращаемые сообщения SOAP должны быть переданы в виде XML-документов — языка разметки, который может считываться как человеком, так и машиной. Завершенный запрос к SOAP API не кэшируется браузером, поэтому он не может быть доступен вторично без повторной отправки в API. На данный момент SOAP — это устаревший стандарт, тем не менее довольно часто используемый enterprise-системами.
Типы запросов
Благодаря тому, что REST API построен поверх HTTP, не важно на каком языке написан frontend (JavaScript или Swift) и backend (Python, Java, C# и пр.), все они смогут взаимодействовать с данным протоколом. Каждый ресурс в REST должен быть идентифицирован посредством стабильного идентификатора, который не меняется при изменении состояния ресурса. Идентификатором в REST является URI. При помощи URL REST API сервер понимает с какими объектами работает, какие объекты ему нужно получить и какие объекты следует удалить.
REST API активно использует методы HTTP протокола и его статуса. В нем присутствуют несколько основных типов запросов:
Если мы говорим о REST как о бизнес-логике, то у нас есть объект и мы передаем статус этого объекта. Например, у нас есть сайт пиццерии и новый заказ. Мы можем заказ создать, узнать о нем подробности, можем обновить его или удалить. И чаще всего для этого используется формат JSON.
Коды запросов
Структура запроса включает в себя маршрут запроса, тип метода, заголовки и тело сообщения. Каждый запрос REST API сопровождается цифровыми кодами. Такие коды называются HTTP-статусами. Они сообщают об успешности запроса.
Статусы разделены на пять групп по своему значению:
Например, редактирование записи на сервере может выполнено успешно (код 200), может быть заблокировано контролем безопасности (код 401 или 403), или не пройти вообще из-за ошибки сервера (код 500).
Чтобы работать с REST API сервисами можно использовать такие инструменты как Postman, SOAP UI (open source утилита по работе с сервисами) и Curl — утилита командной строки, присутствует почти на всех Linux-компьютерах.
Недостатки REST API
Минус этого архитектурного стиля состоит в том, что он завязан на HTTP. Спецификация HTML имеет ограничения и формы, отправляющие данные могут быть реализованы только через GET или POST. Поэтому для корректной работы с другими методами их приходится имитировать. Например, в Rack (механизм на базе которого Ruby взаимодействует с веб-сервером; с использованием Rack сделаны Rails, Merb и прочие Ruby-фреймворки) в форму можно прописать hidden-поле с именем “_method”, а в качестве значения указать имя метода (скажем, «PUT») — при этом будет отправлен POST-запрос, но Rack сможет сделать вид, что получил PUT, а не POST.
Заключение
Теперь вы знаете, что такое REST API и где он применяется. Если говорить понятными словами — это возможность сервера давать доступ клиенту к своим ресурсам. Главный плюс REST API — его простота. Обращение REST API мало чем отличается от обычного запроса к веб-сайту (с небольшим расширением и описанием набора правил, как эти запросы будет происходить).
Недостатком REST API является то, что он опирается на спецификацию HTTP-протокола. Сам по себе REST API не является стандартом, это архитектурный подход. Из этого следует, что он может сильно отличаться у разных компаний. REST удобно использовать в простых случаях и когда важна скорость работы — при работе с мобильным устройством, с JavaScript. В сложных случаях, когда критична поддержка валидации, транзакции — используется SOAP. Помимо REST API имеются и иные способы создания API-систем, такие как JSON-RPC, XML-RPC и GraphQL. Однако на данный момент архитектурный стиль REST API остается самым популярным.
Детальное описание всех кодов REST-запросов (справочник) можно найти здесь — https://restapitutorial.ru/httpstatuscodes.html
Подробнее о REST-проектах, построенных с применением данного архитектурного стиля, а также их отличиях от SOAP сервисов можно узнать из видео ниже:
Введение в 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 не накладывает никаких ограничений на форматы представления ресурсов или на определение сервиса.