Лучшие практики проектирования REST API. Введение в REST API Пишем rest api

Этот пост - ответ на вопрос, заданный в комментарии к одной из моих статей.

В статье я хочу рассказать, что же из себя представляют HTTP-методы GET/POST/PUT/DELETE и другие, для чего они были придуманы и как их использовать в соответствии с REST.

HTTP

Итак, что же представляет из себя один из основных протоколов интернета? Педантов отправлю к RFC2616 , а остальным расскажу по-человечески:)

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

Стартовые строки для запроса и ответа имеют различный формат - нам интересна только стартовая строка запроса, которая выглядит так:

METHOD URI HTTP/VERSION ,

Где METHOD - это как раз метод HTTP-запроса, URI - идентификатор ресурса, VERSION - версия протокола (на данный момент актуальна версия 1.1).

Заголовки - это набор пар имя-значение, разделенных двоеточием. В заголовках передается различная служебная информация: кодировка сообщения, название и версия браузера, адрес, с которого пришел клиент (Referrer) и так далее.

Тело сообщения - это, собственно, передаваемые данные. В ответе передаваемыми данными, как правило, является html-страница, которую запросил браузер, а в запросе, например, в теле сообщения передается содержимое файлов, загружаемых на сервер. Но как правило, тело сообщения в запросе вообще отсутствует.

Пример HTTP-взаимодействия

Рассмотрим пример.

Запрос:
GET /index.php HTTP/1.1 Host: example.com User-Agent: Mozilla/5.0 (X11; U; Linux i686; ru; rv:1.9b5) Gecko/2008050509 Firefox/3.0b5 Accept: text/html Connection: close
Первая строка - это строка запроса, остальные - заголовки; тело сообщения отсутствует

Ответ:
HTTP/1.0 200 OK Server: nginx/0.6.31 Content-Language: ru Content-Type: text/html; charset=utf-8 Content-Length: 1234 Connection: close ... САМА HTML-СТРАНИЦА...

Ресурсы и методы

Вернемся к стартовой строке запроса и вспомним, что в ней присутствует такой параметр, как URI. Это расшифровывается, как Uniform Resource Identifier - единообразный идентификатор ресурса. Ресурс - это, как правило, файл на сервере (пример URI в данном случае "/styles.css"), но вообще ресурсом может являться и какой-либо абстрактный объект ("/blogs/webdev/" - указывает на блок «Веб-разработка», а не на конкретный файл).

Тип HTTP-запроса (также называемый HTTP-метод) указывает серверу на то, какое действие мы хотим произвести с ресурсом. Изначально (в начале 90-х) предполагалось, что клиент может хотеть от ресурса только одно - получить его, однако сейчас по протоколу HTTP можно создавать посты, редактировать профиль, удалять сообщения и многое другое. И эти действия сложно объединить термином «получение».

Для разграничения действий с ресурсами на уровне HTTP-методов и были придуманы следующие варианты:

GET - получение ресурса
POST - создание ресурса
PUT - обновление ресурса
DELETE - удаление ресурса

Обратите внимание на тот факт, что спецификация HTTP не обязывает сервер понимать все методы (которых на самом деле гораздо больше, чем 4) - обязателен только GET, а также не указывает серверу, что он должен делать при получении запроса с тем или иным методом. А это значит, что сервер в ответ на запрос DELETE /index.php HTTP/1.1 не обязан удалять страницу index.php на сервере, так же как на запрос GET /index.php HTTP/1.1 не обязан возвращать вам страницу index.php, он может ее удалять, например:)

В игру вступает REST

REST (REpresentational State Transfer) - это термин был введен в 2000-м году Роем Филдингом (Roy Fielding) - одним из разработчиков протокола HTTP - в качестве названия группы принципов построения веб-приложений. Вообще REST охватывает более широкую область, нежели HTTP - его можно применять и в других сетях с другими протоколами. REST описывает принципы взаимодействия клиента и сервера, основанные на понятиях «ресурса» и «глагола» (можно понимать их как подлежащее и сказуемое). В случае HTTP ресурс определяется своим URI, а глагол - это HTTP-метод.

REST предлагает отказаться от использования одинаковых URI для разных ресурсов (то есть адреса двух разных статей вроде /index.php?article_id=10 и /index.php?article_id=20 - это не REST-way) и использовать разные HTTP-методы для разных действий. То есть веб-приложение, написанное с использованием REST подхода будет удалять ресурс при обращении к нему с HTTP-методом DELETE (разумеется, это не значит, что надо давать возможность удалить всё и вся, но любой запрос на удаление в приложении должен использовать HTTP-метод DELETE).

REST дает программистам возможность писать стандартизованные и чуть более красивые веб-приложения, чем раньше. Используя REST, URI для добавления нового юзера будет не /user.php?action=create (метод GET/POST), а просто /user.php (метод строго POST).

В итоге, совместив имеющуюся спецификацию HTTP и REST-подход наконец-то обретают смысл различные HTTP-методы. GET - возвращает ресурс, POST - создает новый, PUT - обновляет существующий, DELETE - удаляет.

Проблемы?

Да, есть небольшая проблема с применением REST на практике. Проблема эта называется HTML.

PUT/DELETE запросы можно отправлять посредством XMLHttpRequest, посредством обращения к серверу «вручную» (скажем, через curl или даже через telnet), но нельзя сделать HTML-форму, отправляющую полноценный PUT/DELETE-запрос.

Дело в том, спецификация HTML не позволяет создавать формы, отправляющие данные иначе, чем через GET или POST. Поэтому для нормальной работы с другими методами приходится имитировать их искусственно. Например, в Rack (механизм, на базе которого Ruby взаимодействует с веб-сервером; с применением Rack сделаны Rails, Merb и другие Ruby-фреймворки) в форму можно добавить hidden-поле с именем "_method", а в качестве значения указать название метода (например, «PUT») - в этом случае будет отправлен POST-запрос, но Rack сможет сделать вид, что получил PUT, а не POST.

В данной статье я расскажу Вам о том, что такое REST API . Также мы затронем тему HTTP протокола. А также рассмотрим пример архитектурного дизайна REST API.

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

О том, что такое API, я подробно рассказывал . Напомню, что API – это некий набор правил, с помощью которых приложение или какой-либо один его компонент могут взаимодействовать, общаться, если хотите, с другим приложением или компонентом. Прикладной интерфейс программирования (API ) может возвращать данные в разных форматах, например в JSON , XML или в бинарном формате, но в REST API мы будем использовать JSON -формат, как наиболее удобный.

Давайте посмотрим на пример. Возможно, Вы уже знакомы с тем, что такое система контроля версий Git . Ее web-версия – это Github . Так вот, у Github есть собственное API , с помощью которого можно получить какую-либо полезную информацию, например о пользователях и организациях, их проектах, и т.д. Давайте взглянем на пример:

Curl https://api.github.com/orgs/Yandex

В этом примере мы используем консольную утилиту curl для того, чтобы получить данные через API . Ее можно загрузить с официального сайт проекта . Она позволяет делать все то же самое что и расширение curl в PHP , только для этого не нужно писать код, так как вся функциональность доступна посредством интерфейса командной строки. Вообще, незаменимая вещь для тестирования различных прикладных интерфейсов . Есть еще альтернатива в виде расширения для Chrome – Postman .

Данная команда вернет нам большой JSON-объект , содержащий различные данные о компании.

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

Если говорить еще проще то, REST – это архитектурный стиль, а RESTful API – это его практическое воплощение, и чем больше приложение отвечает критериям стиля REST , тем более оно RESTful .

RESTful API сводится к четырем базовым операциям:

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

REST функционирует поверх протокола HTTP , поэтому стоит упомянуть о его основных особенностях. Для каждой операции указанной выше используется свой собственный HTTP метод :

GET – получение
POST – создание
PUT – обновление, модификация
DELETE – удаление

Все эти методы в совокупности называют CRUD (create, read, update, delete) – (создать, прочитать, обновить, удалить) операциями.

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

Т.е. HTTP метод POST соответствует SQL операции INSERT, метод GET – операции SELECT и т.д .

Для каждого HTTP запроса есть свой статус. И они нужны, чтобы грамотно с точки зрения REST API оформить ответ и отдать клиенту. Статусов много, поэтому их всех не перечислить, однако важно знать их группировку:

100 – 199 – это статусы несущие информационный характер
200 - 299 – статусы успешной операции
300 – 399 – статусы перенаправления (редиректа)
400 – 499 – статусы ошибок на стороне клиента
500 – 599 – статусы ошибок на стороне сервера

Вообще, как делается API . Создается некая точка входа для запросов, api.php , например. Этому API , могут передаваться, например, такие запросы:

http://site.com/api.php?action=create.user&id=1&key=46syhy77sash
http://site.com/api.php?action=delete.user&id=1&key=46syhy77sash
http://site.com/api.php?action=get.user&id=1&key=46syhy77sash

где параметр

action – это действие, которое необходимо выполнить
id – идентификатор пользователя
кey – ключ доступа (фактически, временный пароль)

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

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

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

Некоторые скажут:

«Это API , который использует HTTP-запросы для

GET, PUT, POST и DELETE ".

Многие также скажут:

«Речь идет об определении ресурсов с помощью URI»

Другие будут кричать:

В заключение можно сказать:

«В принципе, это просто API , который использует HTTP правильно!»

Некоторые из этих утверждений ошибочны,

Некоторые частично верны,

но это не имеет значения,

Потому что они все упускают суть .

Чтобы иметь возможность разрабатывать API RESTful,

Во-первых,

Что такое REST?

Что такое REST?

REST это:

Определенно не HTTP

Не протокол

Не спецификация

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

И всё-таки...

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

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

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

Желаемая архитектура

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

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

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

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

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

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

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

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

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

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

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

REST все еще не HTTP

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

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

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

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

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

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

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

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

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

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

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

1. Клиент-сервер

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Помните об архитектуре REST

Для меня главное избавление от создания RESTful API заключается в том, насколько важно понимать Интернет и его базовую архитектуру. Мы можем либо воспользоваться этой оптимизацией, либо мы можем игнорировать ее.

Если у вас появились какие-либо вопросы, приглашаем на наши

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

От переводчика:
Я впервые попробовал перевести статью такого объёма и IT-тематики, с радостью прочту ваши комментарии и замечания. Что же касается самой статьи: я не согласен с автором как минимум потому, что, по сути, он заменяет REST на… REST (!!!), но немного в другом обрамлении. Однако, не смотря на то, что в статье преподносится много очевидных вещей, мне она показалась достойной обсуждения на Хабре.

Почему Вам стоит похоронить эту популярную технологию

RESTful api - это чудесно, ведь так?

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

Так на сколько всё же хороша идея REST API? Перед тем как мы разберемся с этим вопросом, давайте посмотрим откуда растут корни…

Откуда вообще взялся REST?

Данная технология стала популярной, когда она была подробно описана и представлена Роем Филдингом в его докторской диссертации под названием Architectural Styles and the Design of Network-based Software Architectures в 2000 году. Рой известен своими вкладами в развитие веба, в особенности HTTP.

Так что же такое RESTful API?

REST - это стиль архитектуры программного обеспечения для построения распределенных масштабируемых веб-сервисов. Рой выступал за использование стандартных HTTP методов так, чтобы придавать запросам определённый смысл.

Таким образом, данные HTTP-запросы будут иметь различную смысловую нагрузку в REST:

GET /object/list
POST /object/list
PUT /object/list

Выше только некоторые виды запросов, а вот весь их список: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE . Если вы даже не слышали о некоторых из них - не беда, так как есть методы, которые практически никогда не поддерживаются ни клиентским, ни серверным приложением.

Рой также утверждал, что HTTP-коды ответов помогут в определении смысла самих ответов. Существует около 38 кодов ответа и ниже вы можете увидеть их список. Названия некоторых я немного сократил для удобства:

Итак, одна транзакция по такому API будет состоять, как минимум, из следующего:

Метод запроса , например, GET
Путь запроса , например, /object/list
Тело запроса , например, форма
Код ответа , например, 200 ОК
Тело ответа , например, данные в формате JSON

Многие положительно отнеслись к такой парадигме и стали использовать её в разработке веб-сервисов с использованием HTTP. Это и есть то, что мы называем RESTful API .

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

На самом деле RESTful API довольно ужасно

REST является отличным механизмом для многих вещей, например, таких как получение контента, и он отслужил нам верой и правдой почти 20 лет. Однако, настало время раскрыть глаза и признать, что концепция RESTful API является одной из худших идей, когда-либо существовавших в веб-разработке. Нет, я не спорю, Рой - отличный парень и, конечно же, у него было множество классных идей… Тем не менее, я не уверен, что RESTful API попадает в их список.

Вскоре мы посмотрим на другое, более правильное решение для построения API, но, перед тем как сделать это, нам следует понять 5 главных проблем RESTful API, которые делают его дорогим, уязвимым к ошибкам и неудобным. Начнём!

Проблема №1: До сих пор нет общего согласования того, что такое RESTful API

Вряд ли кто-то задумывался над тем почему эта технология называется именно «RESTful», а не «RESTpure»? (прим. переводчика: pure - чёткий, понятный ) А потому что никто не может определиться с тем, что из себя представляют все методы запроса, коды ответа, тела и т.д.

Например, когда мы должны использовать код 200 ОК ? Можем ли мы использовать его для подтверждения успешного апдейта записи, или нам стоит использовать код 201 Created ? Судя по всему, нужно использовать код 250 Updated , однако его не существует. И еще, кто-нибудь может объяснить что означает код 417 Expectation failed ?! Кто-нибудь кроме Роя, конечно.

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

Если бы это было единственной проблемой, то я, наверное, смирился бы и продолжал писать RESTful API по сей день. Однако, наш список только раскрывается…

Проблема №2: Словарь REST поддерживается не полностью

Даже если бы мы решили первую проблему, то столкнулись бы со следующей, практической: большинство клиентских и серверных приложений поддерживают не все коды ответа и, собственно, глаголы, означающие HTTP-методы. Например, большинство браузеров имеют ограниченную поддержку PUT и DELETE.

Как же мы с этим справляемся? Одним из способов является вставка глагола , обозначающего нужный метод, в отправляемую форму. Это значит, что в данном случае запрос включает в себя:

Метод HTTP запроса , например, POST
Адрес запроса , например, /object/list
Метод, который мы на самом деле подразумеваем , например, DELETE
Тело запроса , например, данные из формы

Ситуация с кодами ответа не лучше. Разные браузеры (и серверные приложения тоже) часто понимают эти коды по-разному. Например, получив код 307 Temporary redirect , один браузер может позволить пользовательскому скрипту рассмотреть этот ответ и отменить действие до его выполнения. Другой браузер может просто напросто запретить скрипту делать что-либо. На самом деле, единственными кодами, обработки которых можно не бояться, являются 200 ОК и 500 Internal server error . В остальных же случаях поддержка ответов варьируется от «довольно хорошей» до «просто ужасной». Именно по-этому нам часто приходится дополнять тело ответа кодом, который мы на самом деле подразумевали .

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

Проблема №3: Словарь REST недостаточно насыщен

Словарь, состоящий только из HTTP методов и кодов ответа, является слишком ограниченным для эффективной передачи и приёма разнообразной информации, необходимой всем приложениям. Представьте, что мы создали приложение, из которого мы хотим отправить клиенту ответ «render complete». К сожалению, мы не можем сделать это с помощью HTTP кодов, так как, во-первых, такого кода не существует , а во-вторых мы не можем его создать, так как HTTP - не расширяемый . Минутка разочарования. Думаю нам снова придётся вставлять то, что мы подразумеваем в тело ответа.

Также проблема в том, что у нас не один словарь, у нас их три! Коды ответов - это числовые значения (200, 201, 500), которые отличаются от представления методов запроса (GET, POST, PUT и т.д.), а тело ответа и вовсе в формате JSON. Выполнение REST транзакций - это как отправка письма на английском языке в Китай и получение оттуда ответа морзянкой. Все эти сложности являются крупным источником путаницы и ошибок. Вот мы и перешли к следующей глобальной проблеме: дебаггинг.

Проблема №4: RESTful API очень трудно дебажить

Если Вы когда-то работали с REST API, то Вы наверняка в курсе, что его почти невозможно дебажить. Для того, чтобы понять то, что происходит во время транзакции, нам приходится просматривать сразу 7 мест:

Метод HTTP запроса , например, POST
Адрес запроса , например, /object/list
Метод, который мы на самом деле подразумеваем (в теле запроса) , например, DELETE
Собственно, тело запроса , например, данные из формы
Код ответа , например, 200 ОК
Код, который мы подразумевали (в теле ответа) , например, 206 Partial Content
Собственно, тело ответа

Так вот теперь у нас не только два сильно ограниченных словаря, так еще и 7 разных точек в которых может крыться ошибка. Единственное, что могло бы еще более усугубить ситуацию - это если бы технология REST была полностью привязана к одному протоколу и было бы невозможно использовать какой-либо другой канал связи. Собственно, так и есть, и это - наша следующая большая проблема!

Проблема №5: Как правило, RESTful API привязаны к протоколу HTTP

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

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

К счастью, есть хорошее решение, которое позволяет избежать либо минимизировать все проблемы RESTful API. Встречайте!

Шаг вперёд: JSON-pure API

JSON-pure API справляется с большинством проблем, которые мы только что рассмотрели.

Использует только один метод для передачи данных - обычно POST для HTTP и SEND в случае использования Web Sockets
Механизм передачи и содержимое запроса полностью независимы. Все ошибки, предупреждения и данные передаются в теле запроса, в формате JSON
Используется лишь один код ответа, чтобы подтвердить успешную передачу, обычно это 200 ОК
Механизм передачи и содержимое ответа полностью независимы. Все ошибки, предупреждения и данные передаются в теле ответа, в формате JSON
Гораздо проще дебажить, ведь все данные находятся в одном месте в легко-читаемом формате JSON
Легко перенести на любой канал связи, например, HTTP/S, WebSockets, XMPP, telnet, SFTP, SCP, or SSH

JSON-pure API появилось в следствии осознания разработчиками того факта, что RESTful API не особо дружелюбно к браузерам и самим разработчикам. Разделение сообщения и способа передачи делает JSON-pure API быстрым, надежным, простым в использовании, портировании и поиске ошибок. Сегодня, если нам понадобится, например, использовать API Твиттера, то мазохисты выберут RESTful API. Остальные же обратятся к JSON-pure API, или, как его еще называют, «Web API».

За последние десять лет меня не раз просили использовать RESTful вместо JSON-pure. Крайний раз, когда мне чуть было не пришлось поддерживать RESTful API, был в 2011 году. К моему счастью, бэк-енд команда согласилась параллельно с RESTful запустить JSON-pure API, просто перенеся все свои методы и коды в JSON.
Спустя несколько месяцев все мои знакомые, ранее использовавшие RESTful, перешли на JSON-pure, осознав, что это гораздо удобнее.

REST API (Representational State Transfer), или веб-службы RESTful, — что это? REST в переводе c английского «репрезентативная передача состояния». Это способ обеспечения взаимодействия между компьютерными системами в Интернете. REST-совместимые веб-службы, позволяющие запрашивающим системам получать доступ к текстовым представлениям веб-ресурсов и управлять ими, используя единый и предопределенный набор операций. Существуют и другие формы веб-служб, которые содержат свои собственные произвольные наборы операций, например WSDL и SOAP.

REST API: что это? Определение понятия

Веб-ресурсы изначально были определены во Всемирной паутине как документы или файлы, идентифицированные их URL-адресами. Сегодня они имеют гораздо более общее и абстрактное определение, охватывающее каждый предмет или сущность, которые могут быть идентифицированы, названы, адресованы или обработаны в Сети. В веб-службе REST API запросы, отравленные в URI-ресурса, вызывают ответ, который может быть оформлен в XML, HTML, JSON или в каком-либо другом формате. Ответ может подтвердить, что некоторые изменения были внесены в хранимый ресурс, также предоставить гипертекстовые ссылки на другие связанные ресурсы и их коллекции. Использование HTTP как наиболее распространенного протокола относится к типам доступных операций, которые предопределены командами PUT, DELETE, HTTP GET, POST.

Используя протоколы без учета состояния и стандартные операции, системы REST нацелены на быструю производительность, надежность и способность к росту путем повторного использования компонентов, которыми можно управлять и которые можно обновлять, не затрагивая систему в целом. Использование REST часто предпочтительнее, чем более тяжелый стиль SOAP (Simple Object Access Protocol), поскольку REST не использует полосы пропускания, что делает его более подходящим для использования в Интернете. Для подхода SOAP требуется запись или использование предоставленной серверной программы (для обслуживания данных) и клиентской программы (для запроса данных).

История технологии

Термин «репрезентативная передача состояния» был введен и определен в 2000 году Роем Филдингом в его диссертации «Архитектурные стили и дизайн сетевых архитектур программного обеспечения». Он выработал архитектурный стиль REST параллельно с HTTP 1.1 1996-1999 годов, основанный на существующем проекте HTTP 1.0 1996 года. В ретроспективном взгляде на развитие технологии Филдинг сказал о том, что на протяжении процесса стандартизации HTTP он был призван защищать выбор дизайна в Интернете. Это очень сложная задача в рамках процесса, принимающего предложения от кого-либо по теме, которая быстро становится центром всей отрасли.

У Филдинга были комментарии от более чем 500 разработчиков, многие из которых отличные инженеры с многолетним опытом. Он должен был объяснить все, начиная с самых абстрактных понятий веб-взаимодействия и заканчивая точными деталями синтаксиса HTTP. Этот процесс оттачивал его модель до основного набора принципов, свойств и ограничений, которые теперь называются REST.

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

Особенности стиля REST влияют на следующие архитектурные свойства:

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

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

Формальные и архитектурные ограничения

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

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

Безопасность

REST не предоставляет встроенной поддержки безопасности. Это очень важно при проектировании веб-сервисов REST - требования безопасности и проектирования выполняются заранее. Веб-сервисы REST используют HTTP PUT и DELETE из CRUD-операций. PUT и DELETE не поддерживаются многими браузерами и чаще всего отключены на уровне сервера из-за возможного нарушения конфиденциальности. Если он не настроен должным образом на уровне сервера и клиента, любой посторонний пользователь сможет создать ресурс с помощью PUT-метода или уничтожить используемый ресурс DELETE. При разработке требований безопасности для веб-сервисов следует учитывать данные моменты.

Архитектурные элементы

Ключевым аспектом REST является характер и состояние его элементов данных. В стиле REST существует четыре понятия, описывающих поведение и состояние информации.

Ресурс — это объект (логический или физический), доступный в Интернете. Это может быть документ, хранящийся в файловой системе сервера или строка в таблице базы данных. Конечный пользователь взаимодействует с ресурсом для достижения определенной цели. Для проектирования системы с помощью REST разработчик должен думать о бизнес-объектах как ресурсах и о том, как они могут быть адресованы.

URI - уникально идентифицирует ресурс. Этот параметр делает ресурс адресным и может быть изменен. Ресурсы изменяются с использованием протокола приложения - такого как HTTP.

Представление - состояния ресурса в момент времени. Клиент получает представление ресурса при запросе URI. Вид ресурса может быть закодирован в одном или нескольких передаваемых форматах, таких как XML, HTML, JSON, RSS, REST API java. Эти форматы могут быть согласованы при помощи механизма согласования контента.

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

Коннектор

Разъем соединителя представляет собой абстрактный интерфейс, который опосредует связь между компонентами. Поскольку взаимодействия REST не имеют состояния, соединитель не должен хранить информацию о состоянии. Следовательно, связь между компонентами может происходить параллельно.

Клиент и сервер являются основными REST-коннекторами. Клиент инициирует запрос, а сервер его обрабатывает.

Кеш - еще один вид разъема. Кеширование может быть реализовано на клиентских, серверных или промежуточных уровнях. Это уменьшает время ожидания и использование сети.

Компоненты

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

User-Agent - использует клиентский соединитель для инициирования запроса.

Origin-сервер - использует серверный коннектор для ответа на запрос.

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

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

Перспективы развития

Всегда актуален вопрос: REST API — что это для современных интернет-технологий? REST - основа современной веб-архитектуры, которая развивается путем анализа недостатков уже существующих стилей и введения новых дополнений к ней.

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

Статьи по теме