rest like api что это
Что такое REST API. REST, RESTful и RESTlike API, в чем разница?
Representational State Transfer — передача состояния представления.
REST означает передачу репрезентативного состояния. Это архитектурный шаблон для создания веб-сервисов. RESTful реализует этот шаблон.
Что такое REST?
Начнем с определения того, что такое REST, а что нет. Для некоторых REST означает сервер, который обменивается документами JSON с клиентом через HTTP. Это не совсем так. Спецификация REST не требует HTTP или JSON. (В спецификации вообще не упоминается JSON или XML.)
Немного истории REST
Рой Филдинг представил архитектурный паттерн REST в своей дисертации, написанной им в 2000 году. В документе определены средства для клиентов и серверов при помощи которых производится обмена данными между приложениями. Главной особенностью является то, что клиенту ничего не нужно знать о приложении (сервере).
Филдинг не требует особых требований. Вместо этого он определяет REST относительно ограничений и архитектурных элементов.
Архитектурные ограничения REST
Применение ограничений
Во-первых, клиент-сервер, многоуровневая система и ограничения без состояния объединяются, чтобы сформировать приложение с твердыми границами и четким разделением задач. Данные передаются от сервера к клиенту по запросу. Клиент отображает или обрабатывает их. Если состояние изменяется, клиент отправляет его обратно на сервер для хранения. В REST клиент и сервер обмениваются знаниями о данных и состоянии. Архитектура не скрывает данные, она скрывает только реализации.
Ограничения кэшируемого и унифицированного состояния идут еще дальше. Данные приложения доступны клиентам в понятном и последовательном интерфейсе и по возможности кэшированы.
Это техническое определение REST. Как это выглядит в реальном мире?
RPC через HTTP против RESTful
Remote Procedure Call — вызов удалённых процедур. Их часто путают, смотря на URI или на то, как служба использует HTTP-команды. По тому, что складывается впечетлаение, что представление данных в REST это единый набор ресурсов.
Это различие иногда называют различием между вызовами удаленных процедур (RPC) и REST. Для примера разберем метод API для добавления и удаления товаров итернет магазина.
В одной версии есть один URL, который мы запрашиваем с помощью HTTP GET или POST. Мы взаимодействуем со службой, отправляя POST, задавая содержание, которое отражает то, что мы хотим сделать.
Дабавляем новый товар с помощью POST и NewItem:
Запрос данных о товаре с помощью POST и ItemRequest:
Также можно использовать GET.
Удаление или редактирование товаров с помощью POST и ItemDelete или ItemUpdate.
Это не REST. Мы не меняем состояние ресурсов. Мы вызываем функцию с аргументами, которые находятся в JSON или URL.
У службы RESTful есть URI для каждого товара.
Итак, добавление нового товара будет выглядеть как в примере выше.
Но на этом сходство заканчивается. Получение элемента всегда выполняется GET:
Важным моментом является то, что URI работают с данными, а не с удаленными методами.
Но есть еще одна причина, по которой ресурсная модель важна.
REST против RESTful и модель зрелости Ричардсона
Когда вы моделируете свои URI после ресурсов и используете HTTP-команды, вы делаете свой API предсказуемым. Как только разработчики узнают, как вы определили свои ресурсы, они смогут почти предсказать, как будет выглядеть API. Здесь снова упор делается на понимание данных, а не операций.
Но даже если вы не можете сделать API полностью предсказуемым, вы можете задокументировать любую службу REST. Таким образом, каждый элемент, возвращаемый в рассмотреном выше приложении, будет содержать ссылки для удаления, изменения или установки уровня ресурса.
Многие API не соответствуют этому требованию, но называют себя REST. Дело в том, что многие так или иначе нарушают правила. В итоге мы получаем, что многие службы, которые мы называем REST, технически таковыми не являются.
REST, RESTful или RESTlike: имеет ли это значение?
Чем больше требований вы выполните, тем более «full» будет ваше приложение. При выполнении всех требований вы получайте RESTful приложение, если соблюдайте часть из них это RESTlike.
Итак, имеет ли значение сравнение REST и RESTful? Возможно нет. Насколько хорошо ваша архитектура соответствует произвольному стандарту, не так важно, чем то насколько она соответствует вашим потребностям и может ли она расти.
Архитектурный шаблон REST имеет много преимуществ. Филдинг разработал его еще в 2000 году, с тех пор многое изменилось. Но большинство ограничений, которые он имел в виду, все еще с нами. В 2000 году еще не было Android, iPhone или подобных систем. Но Филдинг понял, какие онлайн-приложения нужны и как веб-клиенты будут развиваться из механизмов отображения HTML в законченные приложения. Инструменты, которые мы используем сегодня, адаптированы к 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 отвечает почти за все взаимодействия между серверными и клиентскими приложениями — разберемся, как работает эта технология.
Что такое 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-like API в крупном проекте
Недавно мы перезапустили API Яндекс.Кассы – платежного сервиса с 15-летней историей. Я хочу рассказать, как решить такую амбициозную задачу. Материала набралось на серию статей, поэтому здесь я подробно расскажу о проектировании, переработке наших API, а также про наши инструменты и процессы.
Ключевые слова для оценки полезности: API, REST, OpenAPI, Swagger, рефакторинг взаимодействия систем.
Постановка проблемы, Или о чем этот разговор
Когда маленький коллектив превращается из стартапа в большую компанию, весь объем знаний о программных компонентах и их взаимодействии в уме не удержишь. Отсюда две сложности:
Методологии разработки вроде Scrum позволяют ненадолго снять эти проблемы:
За десять лет разработчики Яндекс.Денег убедились в этом, пройдя путь описания взаимодействий от Wiki-страниц, через XML schema, JSON schema до OpenAPI/Swagger.
Инструменты проектирования спецификаций API – вначале было слово
Все началось с описания порядка взаимодействия сервисов в Wiki и Microsoft Word, с примерами запросов и ответов. Для передачи данных, как правило, использовался XML. Это уже было лучше чем ничего, но такой способ документирования годится только для передачи знаний от человека к человеку.
Произвольное текстовое описание может неоднозначно интерпретироваться людьми из разных подразделений, поэтому потребовалась единая система понятий и терминов. По мере роста количества разработчиков стала необходимой и формализация описаний взаимодействий.
Формальное описание операций, типов данных и их граничных условий нужно не только для разработки, но и для автоматизации модульного тестирования. Первые формальные контракты API-сервисов мы описывали в формате XML schema, позже пробовали и JSON schema. Но оба не идеальны, что мешает полностью перейти на них с текстовых описаний Wiki или Microsoft Word:
Нам идеально подошел OpenAPI, ранее известный как Swagger. OpenAPI Initiative это открытый проект под управлением Linux Foundation. Я убежден, что его ждет большое будущее.
OpenAPI 3 позволяет в одном файле спецификации объединить документацию и описание формата взаимодействия. Это очень важное качество — у вас никогда не будет рассинхронизации текстовой документации и файла спецификации API.
В наших проектах используются OpenAPI 3 файлы спецификаций в формате YAML, и вот почему:
Декомпозиция сервисов и управление изменениями
Типовая проблема, с которой сталкиваются многие организации – управление изменениями документов. Случается так, что параллельно существует множество документов с отдельными изменениями для разных проектов. Поддерживать документацию для множества проектов очень тяжело, поэтому высока вероятность человеческих ошибок.
Спецификация OpenAPI – это текстовый файл в формате YAML, а значит, с ним можно работать как с кодом:
В наших проектах используется система контроля версий Atlassian Bitbucket c плагином Web Pages. Это позволяет одновременно работать со спецификацией, как с кодом, и видеть собранную документацию в HTML-формате.
При декомпозиции какой-либо крупной задачи на набор сервисов рекомендую опираться на принцип разделения функциональности по доменам прикладных областей, а не по технологической общности.
За каждым сервисом API у нас стоит определенный бизнес-процесс, и каждый сервис API описывается отдельным файлом OpenAPI-спецификации. А за него отвечает своя продуктовая команда. С учетом этого, в наборе файлов спецификаций OpenAPI каждый файл соответствует своему прикладному продукту.
Поэтому остальное было делом техники: осталось завести соответствующие репозитории в Bitbucket и настроить группы ревьюеров, ответственных за каждый сервис API. В результате в Bitbucket у нас появился проект для API-спецификаций, представляющий собой общий каталог наших API.
Файлы спецификаций сгруппированы по целевым продуктам:
Иными словами, один репозиторий соответствует одному продукту – команде, ответственной за процессы развития и сопровождения бизнес-процессов продукта и спецификаций его API.
По результатам множества выполненных проектов, структура Git-репозитория стала следующей:
Кроме структуры, пришлось разработать и правила работы с репозиторием:
Благодаря этим принципам мы получили удобную, прозрачную и предсказуемую среду работы со спецификациями.
Подход Design-first как основа качественного решения задачи
При проектировании новых сервисов мы опираемся на принципы REST, но не соблюдаем их в полной мере – например, если это усложняет архитектуру сервиса или противоречит здравому смыслу.
Ценность REST в том, что этот подход обязывает произвести декомпозицию сервиса на набор сущностей и действий с ними.
REST – удобное отражение подхода к проектированию Domain Driven Design. На мой взгляд, благодаря REST-архитектуре у нас получаются более простые и качественные объектные модели прикладных задач, если сравнивать с тем, что мы ранее делали при помощи RPC-подходов.
Чтобы создать качественный продукт, разработчику требуется тщательно изучить предметную область задачи вне контекста опыта предыдущих проектов. Поэтому Design-first хорошо зарекомендовал себя как подход решения прикладных задач. Его можно разбить на два этапа:
Изучение, описание, а также формализация сущностей и процессов предметной области.
Результатом этой работы будет спецификация API сервиса, которая:
Я бы не рекомендовал подход Code-first, когда спецификация API генерируется из существующей реализации: она всегда наследует решения из предыдущих проектов, а не решает задачу. Не существует известных методов решить парадокс курицы и яйца – для создания качественной реализации сперва следует изучить предметную область и провести проектирование сервиса, невозможно создать требуемую реализацию раньше, чем проведено исследование задачи и проектирование.
Антипаттерны REST
Вдохновившись статьей «REST — это новый SOAP», я хотел бы поделиться практическими соображениями по теме примеров некорректного применения REST – ведь это не серебряная пуля и, надеюсь, не золотой молоток в ваших руках.
REST это не только CRUD
Просто удивительно выглядит стремление коллег по цеху упаковать все процессы в модель Create-Read-Update-Delete. Жизнь сложнее и богаче: бизнес-процессы могут состоять из множества операций, сущности могут иметь множество состояний и переходов между ними.
Многие статьи о REST ссылаются на работу Roy Thomas Fielding «Architectural Styles and the Design of Network-based Software Architectures» как первоисточник определения REST (смотрите пятую и шестую главы этой работы). Рекомендаций использовать http- глаголы GET-POST-PUT-DELETE как единственный способ определения операций вы там не найдете.
REST – это принцип декомпозиции сервисов на набор ресурсов и операций над ними. Если вы реализуете всю требуемую функциональность на базе только POST запросов, то это тоже будет REST.
Отражение ошибок бизнес-логики на основе HTTP status
Помните о том, что HTTP-протокол осуществляет транспортную функцию по доставке данных в запросах и ответах. Не следует смешивать уровни бизнес-логики и передачи данных. Четко разделяйте понятия «http-запрос» и «действие бизнес-процесса». HTTP-status коды предназначены для отражения состояния выполнения запроса HTTP, их не следует использовать для задач уровня бизнес-логики.
Тем не менее, мы часто используем сопутствующие протоколы HTTP, которые накладывают свои обязательства на формат ответа, например:
Вот некоторые типовые ситуации, в которых уместно использовать HTTP status:
Отказы уровня бизнес-логики следует отражать как атрибуты сущности, над которой выполнялась операция этим HTTP-запросом.
К примеру, отказ в проведении платежа может быть обусловлен недостатком средств на счете клиента. При этом все http-запросы для проведения платежа будут выполнены успешно. Такую ситуацию следует отражать в виде атрибутов состояния сущности «Платеж».
Использование PUT/PATCH-запросов для операций бизнес-логики
PUT-запросы не всегда подходят для операций бизнес-логики, так как они предназначены для замещения документа на сервере новым документом того же типа и структуры. GET-запрос к тому же ресурсу должен возвращать аргумент PUT-запроса.
Стандарт определяет PUT-запрос как:
The PUT method requests that the state of the target resource be сreated or replaced with the state defined by the representation enclosed in the request message payload.
Пример корректного применения PUT-запроса — загрузка файла на Яндекс.Диск.
RFC 5789 PATCH-запрос тоже ограничен в применимости: его семантика аналогична PUT, тело запроса представляет собой RFC 6902 JSON patch документ, а не любой документ вообще.
Пример JSON patch документа:
Согласитесь, описать операции бизнес-логики простым и доступным способом с таким синтаксисом будет непросто.
Итак, если ваша задача удовлетворяет выше указанным требованиям, используйте PUT/PATCH, в противном случае лучше применять POST.
Пару слов в заключение
ИТ-системы непрерывно развиваются и усложняются. Пожалуй, главным вызовом сегодняшнего дня является ограничение роста сложности систем. По моему мнению, методы правильной декомпозиции систем и управления изменениями это хорошее подспорье в нашем нелегком труде.
Надеюсь, представленный материал был вам полезен. Смотрите также мой доклад о проектировании REST-like API на JavaJam, вот ссылка на запись.