Rest api что нужно знать
REST API
Что такое REST API?
API или программный интерфейс приложения представляет собой набор правил, определяющих способ взаимодействия между приложениями или устройствами. REST API — это API, соответствующий принципам архитектурного стиля REST (от англ. Representational State Transfer — «передача состояния представления»). По этой причине REST API иногда называют RESTful API.
REST (сам термин был введен Роем Филдингом в его докторской диссертации в 2000 году) обеспечивает относительно высокий уровень гибкости и свободы для разработчиков. Но гибкость — лишь одна из причин, объясняющих популярность REST API как способа взаимодействия между компонентами и приложениями в микросервисной архитектуре.
Принципы проектирования REST
На самом базовом уровне API можно представить как механизм, с помощью которого одно приложение или сервис может получить доступ к ресурсу другого приложения или сервиса. Приложение или сервис, запрашивающий доступ, называется клиентом, а приложение или сервис, обладающий необходимым ресурсом, называется сервером.
Некоторые API, например SOAP или XML-RPC, устанавливают строгие ограничения для разработчиков. Однако для разработки REST API можно использовать практически любой язык программирования и разнообразные форматы данных. Единственное требование заключается в соблюдении шести принципов проектирования REST, известных также как архитектурные ограничения:
Принцип работы REST API
REST API используют запросы HTTP для выполнения стандартных функций базы данных, таких как создание, чтение, обновление и удаление записей (так называемые функции CRUD). Например, REST API может использовать запрос GET для получения записи, запрос POST для создания записи, запрос PUT для обновления записи и запрос DELETE для удаления записи. В вызовах API поддерживаются все методы HTTP. Хорошо продуманный REST API можно сравнить с веб-сайтом, который работает в веб-браузере со встроенной поддержкой HTTP.
Состояние ресурса в любой момент времени («отметка времени») называется представлением ресурса. Эта информация может быть предоставлена клиенту практически в любом формате, включая JavaScript Object Notation (JSON), HTML, XLT, Python, PHP или текстовом формате. Популярность JSON обусловлена тем, что данный формат не зависит от языка программирования и понятен как человеку, так и компьютеру.
Важную роль в вызовах REST API также играют заголовки и параметры запросов, поскольку они содержат такую важную информацию, как метаданные, разрешения, универсальные коды ресурсов (URI), сведения о кэшировании, файлы cookie и многое другое. Заголовки запросов и ответов применяются в хорошо продуманных REST API вместе с обычными кодами состояния HTTP.
Рекомендации по использованию REST API
С одной стороны, гибкость является огромным преимуществом при проектировании REST API; с другой стороны, гибкость может стать причиной дефективного или неэффективного API. По этой причине профессиональные разработчики делятся передовыми практиками в спецификациях REST API.
Спецификация OpenAPI (OAS) определяет интерфейс для описания API, чтобы обеспечить разработчикам и приложениям полное понимание всех параметров и возможностей API, включая доступные конечные точки, разрешенные операции для каждой конечной точки, параметры операций, методы аутентификации и прочую информацию. Последняя версия, OAS3 (внешняя ссылка), содержит полезные инструменты, например OpenAPI Generator, для создания клиентов API и серверных заглушек на разных языках программирования.
Для обеспечения безопасности REST API также следует опираться на передовой отраслевой опыт, в частности использование алгоритмов хэширования для защиты паролей и HTTPS для безопасной передачи данных. Для ограничения прав доступа сторонних приложений можно использовать инфраструктуру авторизации, например OAuth 2.0 (внешняя ссылка). Кроме того, API может отклонять любые запросы, поступающие по истечении определенного периода времени, используя отметку времени в заголовке HTTP. Существуют и другие способы контроля доступа к API: проверка параметров и веб-маркеры JSON.
REST API и IBM Cloud
Перечисленные выше преимущества означают, что REST API остается неотъемлемой составляющей процесса разработки программного обеспечения, особенно с ростом спроса на более эффективные интерфейсы взаимодействия с клиентами и приложения для бизнеса и ИТ-операций.
Хорошим способом удовлетворить эти растущие требования является автоматизация. Прежде чем внедрять обширную автоматизацию, начните с небольших проектов, успешность которых можно измерить. Достигнутые результаты можно будет оптимизировать и распространить на новые процессы в других подразделениях организации. Работая с IBM, вы получите доступ к средствам автоматизации на основе ИИ, в том числе и к готовым процессам, которые помогут ускорить внедрение инноваций за счет интеллектуальной составляющей.
Воспользуйтесь инструментами и услугами IBM для решения проблем, связанных с API, включая проблемы безопасности, управления и автоматизации, в ходе модернизации приложений.
Сделайте следующий шаг:
Начните работать с учетной записью IBM Cloud уже сегодня.
Как правильно работать с REST API
Коротко обо мне
Меня зовут Зел, я разработчик-фрилансер из Сингапура. В свободное от работы время я люблю разбираться в коде и попутно публиковать в своем блоге те интересности, которые я обнаружил или изучил.
Вступление
Скорее всего вам уже приходилось слышать о таком термине, как REST API, особенно если вы сталкивались с необходимостью получения данных из другого источника (такого как Twitter или Github). Но что же все-таки это такое? Что мы можем с этим делать и как мы можем это использовать?
В данной статье вы узнаете все о REST API для того, чтобы работать с ними и читать связанную с ними документацию.
Что же такое REST API?
Давайте представим, что вы пытаетесь найти фильмы о Бэтмене на YouTube. Вы открываете сайт, вбиваете в форму поиска слово «Бэтмен», жмакаете «Окей» и видите список фильмов о супергерое. Похожим образом работает и WEB API. Вы ищите что-то и получаете список результатов от запрашиваемого ресурса.
Дословно API расшифровывается как Application Programming Interface. Это набор правил, позволяющий программам «общаться» друг с другом. Разработчик создает API на сервере и позволяет клиентам обращаться к нему.
REST – это архитектурный подход, определяющий, как API должны выглядеть. Читается как «Representational State Transfer». Этому набору правил и следует разработчик при создании своего приложения. Одно из этих правил гласит, что при обращении к определенному адресу, вы должны получать определенный набор данных (ресурс).
Анатомия запроса
Маршрут – это адрес, по которому отправляется ваш запрос. Его структура примерно следующая:
Путь определяет запрашиваемый ресурс. Это что-то вроде автоответчика, который просит вас нажать 1 для одного сервиса, 2 для другого и так далее.
Для понимания того, какие именно пути вам доступны, вам следует просмотреть документацию. К примеру, предположим, вы хотите получить список репозиториев для конкретного пользователя на Git. Согласно документации, вы можете использовать следующий путь для этого:
Вам следует подставить под пропуск имя пользователя. К примеру, чтобы найти список моих репозиториев, вы можете использовать маршрут:
Последняя часть маршрута – это параметры запроса. Технически запросы не являются частью REST-архитектуры, но на практике сейчас все строится на них. Так что давайте поговорим о них более детально. Параметры запроса позволяют использовать в запросе наборы пар «ключ-значение». Они всегда начинаются знаком вопроса. Каждая пара параметров после чего разделяется амперсантом (что-то вроде этого):
Как только вы пытаетесь получить список репозиториев для пользователя, вы добавляете эти три опциональных параметра и после чего получаете следующий результат:
Тема связана со специальностями:
Если же вы желаете получить список моих недавно запушеных репозиториев, вам следует ввести следующее:
Итак, как же понять, что маршруты рабочие? Что ж, пришло время проверить их на практике!
Тестирование при помощи Curl
Вы моете отправить запрос при помощи любого языка программирования. JavaScript может использовать методы вроде Fetch API или JQuery`s Ajax Method. Руби использует другое. И так далее.
В этой статье я буду использовать такую утилитку, как Curl. Дело в том, что она указана в официальной документации для веб-сервисов. Если вы поймете, как использовать эту утилиту, вы поймете, как работать с API. После чего вы можете производить запросы любым удобным для вас языком.
Перед тем, как продолжить, вам следует убедится, что Curl установлен на вашей машине.
Ели же он не установлен, самое время установить. В таком случае вы получите ошибку «command not found».
Для того, чтобы использовать утилиту, необходимо ввести следующее (по примеру):
И как только вы подтверждаете ввод, вы получаете ответ (наподобие этого):
Чтобы получить список пользовательских репозиториев, вам следует изменить запрос по тому же принципу, который был оговорен ранее. К примеру, чтобы получить список моих репозиториев, вам следует ввести следующее:
Если же вы желаете включить параметры запросов, убедитесь, что вы их экранируете. Дело в том, что без экранирования знаки вопроса и равно расцениваются системой как спец. символы и выполнение команды произойдет с ошибкой.
Также попробуйте другие команды и произведите запросы! В результате вы получаете похожие ответы.
JSON
JSON – JavaScript Object Notation – общий формат для отправки и приема данных посредством REST API. Ответ, отправляемый Github, также содержится в формате JSON.
Содержание объекта этого формата примерно следующее:
Возвращаемся к анатомии запроса
Теперь же давайте попробуем разобраться с остальным.
Тип метода
GET – используется для получения со стороны севера определенного ресурса. Если вы производите этот запрос, сервер ищет информацию и отправляет ее вам назад. По сути, он производит операцию чтения на сервере. Дефолтный тип запросов.
POST – нужен для создания определенного ресурса на сервере. Сервер создает в базе данных новую сущность и оповещает вас, был ли процесс создания успешным. По сути, это операция создания.
PUT и PATCH – используются для обновления определенной информации на сервере. В таком случае сервер просто изменяет информацию существующих сущностей в базе данных и оповещает об успехе выполнения операции.
DELETE – как и следует из названия, удаляет указанную сущность из базы или сигнализирует об ошибке, если такой сущности в базе не было.
Сам же API позволяет указать, какой метод должен быть использован в определенных контекстных ситуациях.
GET запрос в этом случае необходим, чтобы получить список всех репозиториев указанного пользователя. Также можно использовать curl:
Попробуйте отправить этот запрос. В качестве ответа вы получите требование об аутентификации.
Заголовки
Заголовки используются, чтобы предоставить информацию как клиенту, так и серверу. Вообще, их можно использовать для много чего – пример – та же самая аутентификация и авторизация. Найти список доступных заголовком можно на официальной странице MDN.
Видео курсы по схожей тематике:
SQL Базовый. Разбор ДЗ
Практикум курса C# Стартовый на примерах из GTA 5
Выполнение домашнего задания по курсу C# Стартовый
Заголовки представляют из себя пары ключей-значений. Пример:
Также пример с использованием curl:
(Примечание: заголовок Content-Type в случае Github для работы не является обязательным. Это всего лишь пример использования заголовка в запросе, ничего более.)
Для просмотра отправленных заголовком можно использовать следующее:
Здесь звездочка относится к дополнительной информации, предоставленной посредством curl. > относится к заголовкам запроса, а Александр Залуцкий
Memory Game на JavaScript за 2 часа
Как стать PHP разработчиком?
К примеру, Твиттер использует первый метод. На момент написания версия Твиттер API была 1.1.
С другой стороны, GitHub использует другой способ:
В заключение
В этой статье мы рассмотрели, что такое REST API и как его можно использовать совместно с curl. Кроме того, вы также выучили, как залогиниться при помощи запроса и что такое статус-код.
Я искренне надеюсь, что эта статья позволила вам повысить свой уровень общих и не очень познаний касательно такого немаловажного аспекта веб-разработки. Буду рад любым вашим комментариям здесь.
Автор перевода: Евгений Лукашук
Еще больше материалов по данной теме:
Введение в Rest API: что это простыми словами
REST API отвечает почти за все взаимодействия между серверными и клиентскими приложениями — разберемся, как работает эта технология.
Что такое REST API
Representational State Transfer (REST) в переводе — это передача состояния представления. Технология позволяет получать и модифицировать данные и состояния удаленных приложений, передавая HTTP-вызовы через интернет или любую другую сеть.
Если проще, то REST API — это когда серверное приложение дает доступ к своим данным клиентскому приложению по определенному URL. Далее разберем подробнее, начиная с базовых понятий.
Базовые понятия Rest API — HTTP-протокол и API
Application Programming Interface (API), или программный интерфейс приложения — это набор инструментов, который позволяет одним программам работать с другими. API предусматривает, что программы могут работать в том числе и на разных компьютерах. В этом случае требуется организовать интерфейс API так, чтобы ПО могло запрашивать функции друг друга через сеть.
Также API должно учитывать, что программы могут быть написаны на различных языках программирования и работать в разных операционных системах.
Бухгалтерское приложение для выставления счетов. Счета хранятся на сервере: мобильное приложение обращается к нему через API и показывает на экране то, что нужно.
REST API позволяет использовать для общения между программами протокол HTTP (зашифрованная версия — HTTPS), с помощью которого мы получаем и отправляем большую часть информации в интернете.
HTTP довольно прост. Посмотрим на его работу на примере. Допустим, есть адрес http://website.com/something. Он состоит из двух частей: первая — это адрес сайта или сервера, то есть http://website.com. Вторая — адрес ресурса на удаленном сервере, в данном примере — /something.
Вбивая в адресную строку URL-адрес http://website.com/something, мы на самом деле идем на сервер website.com и запрашиваем ресурс под названием /something. «Пойди вот туда, принеси мне вот то» — и есть HTTP-запрос.
Пример HTTP-запроса к серверу
Теперь представим, что по адресу website.com работает программа, к которой хочет обратиться другая программа. Чтобы программа понимала, какие именно функции нужны, используют различные адреса.
В бухгалтерском сервисе работа со счетами может быть представлена в API ресурсом /invoices. А банковские реквизиты — ресурсом /requisites. Названия ресурсов придумывают по правилам формирования URL в интернете.
Методы HTTP: основа работы REST API
Чтобы ресурс, который вы запрашиваете, выполнял нужные действия, используют разные способы обращения к нему. Например, если вы работаете со счетами с помощью ресурса /invoices, который мы придумали выше, то можете их просматривать, редактировать или удалять.
В API-системе четыре классических метода:
Таким образом, мы получаем четыре функции, которые одна программа может использовать при обращении к данным ресурса, в примере — это ресурс для работы со счетами /invoices.
Для чего используют REST API
Архитектура REST API — самое популярное решение для организации взаимодействия между различными программами. Так произошло, поскольку HTTP-протокол реализован во всех языках программирования и всех операционных системах, в отличие от проприетарных протоколов.
Чаще всего 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 сервисов можно узнать из видео ниже: