Чем отличается REST API от RESTful API?
Объясните пожалуйста простым языком в чем отличия REST Api и RESTful API? В интернете абстрактно описано.
Отслеживать
13.7k 12 12 золотых знаков 43 43 серебряных знака 75 75 бронзовых знаков
задан 13 июн в 13:52
sagittarius sagittarius
41 7 7 бронзовых знаков
2 ответа 2
Сортировка: Сброс на вариант по умолчанию
REST — это аббревиатура (REpresentational State Transfer = передача самоописываемого состояния), обозначающая некоторые полезные свойства клиент-серверной архитектуры
RESTful — это прилагательное к слову REST
чем отличается Rest Api и Restful 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, в том числе REST и SOAP API. Веб-сервисы — это, в основном, запросы и ответы между клиентами и серверами (компьютер запрашивает ресурс, а веб-сервис отвечает на запрос).
API, использующие протокол HTTP для передачи запросов и ответов, рассматриваются как «веб-сервисы». В случае веб-сервисов клиент, делающий запрос на ресурс, и сервер API, предоставляющий ответ, могут использовать любой язык программирования или платформу. Не имеет значения, какой ЯП или платформа будут использоваться, потому что запрос сообщения и ответ сделаны через общий веб-протокол HTTP.
Веб-протокол является частью прекрасного веб-сервисов: они независимы от языка и поэтому совместимы между различными платформами и системами. При документировании REST API не имеет значения, строят ли инженеры API с помощью Java, Ruby, Python или какого-либо другого языка. Запросы выполняются через HTTP, и ответы возвращаются через HTTP.
Диаграмма ниже показывает общую модель REST API:
Как видно, между клиентом и сервером API существует запрос и ответ. Клиент и сервер могут быть основаны на любом языке, но HTTP — это протокол, используемый для передачи сообщения. Этот шаблон запроса и ответа, по сути, является принципом работы API REST.
Любой язык программирования, создающий запрос, будет по-своему отправлять веб-запрос и анализировать ответ на своем языке. Эти специфичные для языка функции отправки запросов и анализа ответов не являются частью REST API (хотя они могут быть предоставлены в прилагаемом SDK). REST API не зависит от языка и обрабатывает входящую и исходящую информацию по HTTP.
API-интерфейсы SOAP являются предшественниками REST API
До того, как REST стал самым популярным веб-сервисом, SOAP (Simple Object Access Protocol) был гораздо более распространенным. Чтобы лучше понять REST, полезно иметь некоторое понимание SOAP. Заодно и увидеть, что отличает SOAP и REST.
SOAP — это стандартизированный протокол, который требует XML в качестве формата сообщений для запросов и ответов. Как стандартный протокол, формат сообщения обычно определяется с помощью файла WSDL (язык описания веб-служб).
Файл WSDL определяет разрешенные элементы и атрибуты в обмениваемых сообщениях. Файл WSDL является машиночитаемым и используется серверами, взаимодействующими друг с другом для облегчения связи.
Сообщения SOAP заключены в «конверт», который включает в себя заголовок и тело, используя определенную схему XML и пространство имен. Пример формата запроса и ответа SOAP см. SOAP против REST 101: понимание различий.
Основная проблема с SOAP заключается в том, что формат сообщений XML слишком многословный и тяжелый. Особенно это проблематично в мобильных сценариях, где размер файла и пропускная способность играют решающее значение. Многословный формат сообщения замедляет время обработки, что делает взаимодействия SOAP вялым.
SOAP по-прежнему используется в enterprise приложениях (особенно в финансовых учреждениях) со связью server-to-server, но в последние годы SOAP вымещается REST, особенно для API открытых сетей.
REST — стиль, а не стандарт
Как и SOAP, REST (Representational State Transfer) использует HTTP в качестве протокола передачи данных для запросов и ответов. Однако, в отличие от SOAP, REST является архитектурным стилем, а не стандартным протоколом. Вот почему REST API иногда называют RESTful API — 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 экземпляров ресурса.
Вот пример, как выглядит конечная точка:
http://apiserver.com/homes?limit=5&format=json Конечная точка показывает весь путь к ресурсу. Однако в документации вы обычно разделяете этот URL на более конкретные части:
- Базовый путь (базовый URL или хост) относится к общему пути для API. В приведенном выше примере базовый путь — http://apiserver.com;
- Отношение конечной точки к конечному пути этой точки. В приведенном примере это /homes ;
- ?limit=5&format=json часть конечной точки содержит параметры строки запроса для этой точки.
В приведенном выше примере конечная точка получит ресурс «homes» и ограничит результат до 5 домов. Будет возвращен ответ в формате JSON.
Можно иметь несколько конечных точек, которые ссылаются на один и тот же ресурс. Вот один из вариантов:
http://apiserver.com/homes/
Приведенный выше URL-адрес может быть конечной точкой, которая извлекает домашний ресурс, содержащий определенный идентификатор. То, что передается обратно с сервера на клиент, является «представлением» ресурса. Ресурс может иметь много разных представлений (показывая все дома или дома, которые соответствуют определенным критериям, или дома в определенном формате и т.д.), Но здесь мы хотим видеть дом с определенным идентификатором.
Tip: Отношения между ресурсами и методами часто описывается в терминах «существительные» и «глаголы». Ресурс — это существительное, потому что это объект или вещь. Глагол — это то, что вы делаете с этим существительным. Объединяя существительные с глаголами, вы формируете язык REST.
Более подробно рассмотрим конечные точки в следующих разделах (например, в Обзоре руководства описания API мы рассмотрим каждое свойство ресурса). А здесь дан краткий обзор.
Сама сеть следует за REST
Термины «запросы GET» и «ответы на сообщения», передаваемые по «протоколу HTTP», могут показаться незнакомыми, но это всего лишь официальная терминология REST для описания происходящего. Поскольку мы используем Интернет, мы уже знакомы с тем, как работают API-интерфейсы REST — сама сеть по сути следует стилю RESTful.
Когда мы открываем браузер и переходим на https://idratherbewriting.com, в действительности мы используем протокол HTTP ( http: // ) для отправки запроса GET на ресурс, доступный на веб-сервере. Ответ от сервера отправляет контент с этого ресурса обратно по протоколу HTTP. Наш браузер — это просто клиент, который делает ответ на сообщение читаемым и знакомым нашему глазу.
Можно увидеть этот ответ в 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 для описания элементов и параметров, разрешенных в запросах и ответах.
Хотя и существует возможный файл WADL (Web Application Description Language), который можно использовать для описания API-интерфейсов REST, им используются редко, поскольку там неадекватно описываются все ресурсы, параметры, форматы сообщений и другие атрибуты API-интерфейса REST. , (Помните, что REST API — это архитектурный стиль, а не стандартизированный протокол.)
Чтобы понять, как взаимодействовать с REST API, нужно прочитать документацию по API. Необходимость читать документы делает роль технического писателя чрезвычайно важной для документирования API.
Некоторые формальные спецификации — например, OpenAPI и RAML — были разработаны для описания API REST. Когда вы описываете свой API с использованием спецификации OpenAPI или RAML, инструменты, которые могут читать эти спецификации (например, Swagger UI или консоль RAML 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 и RESTful api?
Объяснити пожалуйста как для 5 летнего ребенка, потому что то как написано в википедии до меня не доходит.
- Вопрос задан более трёх лет назад
- 80087 просмотров
Комментировать
Решения вопроса 0
Ответы на вопрос 5
private_tm @private_tm
Одно и тоже. По факту обычный текстовый проток запросов ответов
запрос
https://toster.ru/?question=»Как тебя зовут?»
ответ в формате json
name: «Вася»
ПС: рановато ребенку 5-ти лет такое знать))
ПС ПС не так прочитал))
Ответ написан более трёх лет назад
Нравится 6 1 комментарий
Имхо, это не Restful запрос, т.к. нет URI для ресурса.
Для Restful запрос должен быть вроде:
Антон Дзодзиков @DzodzikovAK
Java Developer
REST — набор архитектурных принципов построения сервис-ориентированных систем.
RESTful — прилагательное, употребляющееся по отношению к сервисам, которые следуют принципам REST.
Лучшие практики проектирования REST API
Здравствуйте, дорогие читатели! Прежде чем вы начнёте читать эту статью, я хотел бы описать цели её создания и рассказать, что побудило меня на её написание.
На одном из проектов нашей компании появилось необходимость спроектировать серверное приложение в стиле REST. Изначально нам казалось, что это довольно простая задача и для её решения нам хватит только собственного опыта.
Но, когда стартовал процесс разработки архитектуры и приведения REST-сервисов к единому стилю, у нас с коллегами начали возникать спорные вопросы и появляться разные точки зрения на реализацию того или иного аспекта. Здесь мы поняли, что необходимо открыть гугл и обратиться к помощи коллективного разума, изучить предлагаемые лучшие практики, которые необходимо использовать при проектировании RESTful приложения.
Данная статья будет полезна для тех людей, которые уже имеют некоторый опыт работы с веб-приложениями (и, возможно, с REST-сервисами), но нуждаются в закреплении и стандартизации полученных знаний.
Определение
Для начала нужно определиться, что же такое REST. Википедия даёт на этот вопрос следующий ответ. REST (Representational State Transfer — «передача состояния представления») — архитектурный стиль взаимодействия компонентов распределённого приложения в сети. REST представляет собой согласованный набор ограничений, учитываемых при проектировании распределённой гипермедиа-системы.
Своими словами я бы объяснил понятие REST как «набор рекомендаций, который позволяет унифицировать взаимодействие клиентских и серверных приложений».
В данной статье я постараюсь рассказать об этих самых «рекомендациях», которые помогут проектировать и создавать REST-сервисы согласно общепринятым практикам.
Также нужно понимать, что такое REST-сервис. Я бы дал определение REST-сервису, как «точка взаимодействия клиентского приложения с сервером». Говоря Java терминологией — это сервлет, на который клиент посылает запрос.
Проблематика
Но прежде чем начинать описывать правила, я хотел бы донести мысль о том, что REST — это не стандарт, потому нет единых строгих правил, которых стоит придерживаться. Это значит, что до сих пор нет полной согласованности о том, какие решения лучше применять в той или иной ситуации. Очень часто заходят споры о том, какие HTTP методы использовать и какой HTTP код возвращать в каждой конкретной ситуации.
Более подробно о проблемах REST можно почитать здесь.
Соответственно, рекомендации, которые я опишу ниже, стоит принимать во внимание, но не следовать им на 100%, если это может повредить какому-либо другому аспекту проекта.
Однако если вы будете следовать всем рекомендациям, то получится спроектировать очень понятную и поддерживаемую систему, с которой приятно работать.
Название сервиса
Для начала необходимо выбрать имя для REST сервиса. Под именем сервиса я подразумеваю его путь в URI запросе. Например, http://my-site.by/api/rest/service/name . Для выбора имени нам нужно понимать, что такое «ресурсы» в архитектуре REST.
Представление ресурса
В терминологии REST что угодно может быть ресурсом — HTML-документ, изображение, информация о конкретном пользователе и т.д. Если ресурс представляет собой некоторый объект, его легко представить, используя некоторый стандартный формат, например, XML или JSON. Далее сервер может отправить данный ресурс, используя выбранный формат, а клиент сможет работать с полученным от сервера ресурсом, используя этот же формат.
Пример представления ресурса «профиль» в формате JSON:
REST не накладывает явных ограничений на формат, который должен быть использован для представления ресурсов, но есть ряд правил, которым нужно следовать при разработке формата, который будет использоваться для представления ресурса:
- Клиент и сервер должны «понимать» и иметь возможность работать с выбранным форматом.
- Ресурс можно полностью описать, используя выбранный формат независимо от сложности ресурса.
- Формат должен предусматривать возможность представления связей между ресурсами.
Пример представления ресурса «заказ» и его связи с ресурсом «профиль»:
Как видно, не обязательно полностью дублировать всю структуру ресурса, на который ссылается другой ресурс. Вместо этого можно использовать понятную ссылку на другой ресурс.
Обращение к ресурсу
Каждый ресурс должен быть уникально обозначен постоянным идентификатором. «Постоянный» означает, что идентификатор не изменится за время обмена данными, и даже когда изменится состояние ресурса. Если ресурсу присваивается другой идентификатор, сервер должен сообщить клиенту, что запрос был неудачным и дать ссылку на новый адрес. Каждый ресурс однозначно определяется URL. Это значит, что URL по сути является первичным ключом для единицы данных. То есть, например, вторая книга с книжной полки будет иметь вид /books/2, а 41 страница в этой книге — /books/2/pages/41. Отсюда и получается строго заданный формат. Причём совершенно не имеет значения, в каком формате находятся данные по адресу /books/2/pages/41 – это может быть и HTML, и отсканированная копия в виде jpeg-файла, и документ Word.
Рекомендуется при определении имени REST-сервиса использовать имена ресурсов во множественном числе. Такой подход позволяет добавлять новые REST-сервисы, лишь расширяя имена уже существующих. Например, сервис /books вернёт нам список всех книг, /books/3 вернёт информацию о 3-ей книге, а сервис /books/3/pages вернёт все страницы 3-ей книги.
Для сервисов, которые выполняют какие-то специфические действия над ресурсом, есть 2 подхода для указания действия: в имени сервиса или в его параметрах. Например, /books/3/clean или /books/3?clean. Я предпочитаю первый вариант, так как обычно такие сервисы не редко используют POST методы, которые не поддерживают передачу параметров в URl, что делает сервис, на мой взгляд, не очень читабельным. Используя определение типа действия в имени сервиса, мы делаем наш сервис более расширяемым, так как он не зависит от типа HTTP метода.
Также очень не рекомендуется использовать имена, включающие в себя несколько слов и описывающие бизнес составляющую сервиса (как это рекомендуется делать при именовании java методов). Например, вместо /getAllCars лучше сделать метод /cars. Если же метод нельзя никак описать одним словом, то необходимо применять единый стиль разделителей, я обычно использую ‘-’, что является наиболее популярным подходом. Например, /cars/3/can-sold.
Более подробно о проектировании названий REST-сервисов можно прочитать в этой статье.
HTTP методы
Далее нам необходимо выбрать HTTP метод, который будет использовать наш REST-сервис, ведь имея даже одинаковое имя, но разные методы, REST-сервисы выполняют совершенно различные действия.
В REST используются 4 основных HTTP метода: GET, POST, PUT, DELETE. В большинстве случаев каждый из методов служит для выполнения предопределённого ему действия из CRUD (create, read, update, delete — «создание, чтение, обновление, удаление»).
POST — create, GET — read, PUT — update, DELETE — delete.
ВАЖНОЕ ДОПОЛНЕНИЕ: Существуют так называемые REST-Patterns, которые различаются связыванием HTTP-методов с тем, что они делают. В частности, разные паттерны по-разному рассматривают POST и PUT. Однако, PUT предназначен для создания, замены или обновления, для POST это не определено (The POST operation is very generic and no specific meaning can be attached to it). Поэтому иногда POST и PUT можно поменять местами. Но в большинстве случаев POST используют для создания, а PUT для редактирования, и чуть позже я объясню почему.
Приведу несколько примеров использования различных методов для взаимодействия с ресурсами.
- GET /books/ – получает список всех книг. Как правило, это упрощённый список, т.е. содержащий только поля идентификатора и названия объекта, без остальных данных.
- GET /books/ – получает полную информацию о книге.
- POST /books/ – создаёт новую книгу. Данные передаются в теле запроса.
PUT /books/ – изменяет данные о книге с идентификатором , возможно, заменяет их. Данные также передаются в теле запроса. - OPTIONS /books – получает список поддерживаемых операций для указанного ресурса (практически не используется).
- DELETE /books/ – удаляет данные с идентификатором .
Безопасность и идемпотентность
Очень помогут в выборе HTTP метода знания о безопасности и идемпотентности этих методов.
Безопасный запрос — это запрос, который не меняет состояние приложения.
Идемпотентный запрос — это запрос, эффект которого от многократного выполнения равен эффекту от однократного выполнения.
Судя по данной таблице, GET-запрос не должен менять состояние ресурса, к которому применяется. PUT и DELETE запросы могут менять состояние ресурса, но их можно спокойно повторять, если нет уверенности, что предыдущий запрос выполнился. В принципе, это логично: если многократно повторять запрос удаления или замены определённого ресурса, то результатом будет удаление или замена ресурса. Но POST запрос, как мы видим из таблицы, небезопасный и неидемпотентный. То есть мало того что он меняет состояние ресурса, так и многократное его повторение будет производить эффект, зависимый от количества повторений. Ему по смыслу соответствует операция добавления новых элементов в БД: выполнили запрос Х раз, и в БД добавилось Х элементов.
Также приведу пример того, почему GET-запросы не должны изменять состояние ресурса. GET-запросы могут кэшироваться, например, на уровне прокси-сервера. В таком случае запрос может даже не дойти до сервера приложения, а в качестве ответа прокси-сервер вернёт информацию из кэша.
HTTP коды
В стандарте HTTP описано более 70 статус кодов. Хорошим тоном является использование хотя бы основных.
- 200 – OK – успешный запрос. Если клиентом были запрошены какие-либо данные, то они находятся в заголовке и/или теле сообщения.
- 201 – OK – в результате успешного выполнения запроса был создан новый ресурс.
- 204 – OK – ресурс успешно удалён.
- 304 – Not Modified – клиент может использовать данные из кэша.
- 400 – Bad Request – запрос невалидный или не может быть обработан.
- 401 – Unauthorized – запрос требует аутентификации пользователя.
- 403 – Forbidden – сервер понял запрос, но отказывается его обработать или доступ запрещён.
- 404 – Not found – ресурс не найден.
- 500 – Internal Server Error – разработчики API должны стараться избежать таких ошибок.
Эти ошибки должны быть отловлены в глобальном catch-блоке, залогированы, но они не должны быть возвращены в ответе.
Чем обширнее набор кодов, который мы будем использовать, тем более понятный будет API, который мы создаём. Однако нужно учесть, что некоторые коды браузеры обрабатывают по-разному. Например, некоторые браузеры получив код ответа 307 сразу же выполняют редирект, а некоторые позволяют обработать такую ситуацию и отменить действие. Прежде чем использовать тот или иной код, необходимо полностью понимать, как он будет обрабатываться на клиентской стороне!
Более подробно о HTTP кодах можно почитать здесь.
Headers
Рекомендуется при проектировании REST-сервисов явно указывать заголовки, в которых обозначен формат обмена данными:
- Content-Type — формат запроса;
- Accept — список форматов ответа.
Параметры поиска ресурсов
Чтобы упростить использование сервисов, отвечающих за возвращение какой-либо информации, и вдобавок сделать их наиболее производительными, необходимо использовать в качестве параметров запроса параметры для сортировки, фильтрации, выбора полей и пагинации.
Фильтрация
Используйте уникальный параметр запроса для каждого поля, чтобы реализовать фильтрацию. Это позволит ограничить количество выводимой информации, что оптимизирует время обработки запроса.
Например, чтобы вывести все красные книги необходимо выполнить запрос:
GET /books?color=red
Сортировка
Сортировка реализуется подобно фильтрации. Например, чтобы вывести все книги, отсортированные по году публикации по убыванию и по названию по возрастанию, нужно выполнить следующий запрос:
GET /books?sort=-year,+name
Пагинация
Для того чтобы поддержать возможность загрузки списка ресурсов, которые должны отображаться на определённой странице приложения, в REST API должен быть предусмотрен функционал пагинации. Реализуется он с помощью знакомых нам по SQL параметрам limit и offset. Например:
GET /books?offset=10&limit=5
Помимо того, хорошим тоном является вывод ссылок на предыдущую, следующую, первую и последнюю страницы в хидере Link. Например:
Рекомендуется также возвращать общее количество ресурсов в хидере X-Total-Count.
Выбор полей ресурса
Для более удобного использования сервиса, для экономии трафика можно предоставить возможность управлять форматом вывода данных. Реализуется предоставлением возможности выбора полей ресурса, которые должен вернуть REST сервис. Например, если необходимо получить только id книг и их цвета, необходимо выполнить следующий запрос:
GET /books?fields=id,color
Хранение состояния
Одно из ограничений RESTful сервисов заключается в том, что они не должны хранить состояние клиента, от которого получают запросы.
Пример сервиса, не хранящего состояние:
Request1: GET http://MyService/Persons/1 HTTP/1.1
Request2: GET http://MyService/Persons/2 HTTP/1.1
Каждый из этих запросов может быть обработан независимо от другого.
Пример сервиса, хранящего состояние:
Request1: GET http://MyService/Persons/1 HTTP/1.1
Request2: GET http://MyService/NextPerson HTTP/1.1
Чтобы обработать второй запрос, серверу потребуется «запомнить» id последнего человека, который был запрошен клиентом. Т.е. сервер должен «запомнить» своё текущее состояние, иначе второй запрос не может быть обработан. При проектировании сервиса следует избегать необходимости в хранении состояния, так как это имеет ряд преимуществ.
Преимущества сервиса, не хранящего состояние:
- сервис обрабатывает запросы независимо друг от друга;
- архитектура сервиса упрощается;
- не требуется дополнительных усилий для реализации сервисов с использованием протокола HTTP, который также не хранит состояния.
Недостатки сервиса, не хранящего состояние:
- клиент сам должен отвечать за передачу необходимого контекста сервису.
Версионность
Хорошим тоном является поддержка версионности REST API. Это позволит в дальнейшем легко расширять API, без обязательного внесения изменений в клиенты, которые уже пользуются им.
Имеются несколько подходов реализации версионности:
- С использованием Accept хидера. В данном случае версия API указывается в Accept — Accept:text/v2+json
- С использованием URI. В таком подходе версия API указывается прямо в URI — http://localhost/api/v2/books
- Использование кастомного хидера. Можно использовать собственный хидер, который будет отвечать только за передачу версии API — API-Version:v2
- Использование параметра запроса. Можно использовать параметр запроса для передачи версии API — /books?v=2
Каждый из представленных способов имеет право на существование, у каждого есть свои плюсы и минусы. Однако только вам решать, какой способ реализации версионности подойдёт вашему проекту.
Документация
Для удобного пользования нашими REST сервисами нужно создать хорошую и понятную документацию. Для этих целей можно использовать различные инструменты, например, Mashape или Apiary, но я рекомендую использовать Swagger.
Swagger — это технология, которая позволяет документировать REST-сервисы. Swagger поддерживает множество языков программирования и фреймворков. Плюс, Swagger предоставляет UI для просмотра документации.
Получить более подробную информацию о Swagger можно по данной ссылке.
Архивирование
Для экономии трафика рекомендуется использовать архивирование, при передаче больших данных. Это сократит время выполнения запроса. В большинстве современных фреймворков данная функция реализована по умолчанию.
Кэширование
Также для сокращения запросов к БД и увеличения быстродействия наших REST сервисов рекомендуется применить механизм кэширования. Кэширование можно настраивать как на уровне сервера, так и в самом приложении, в зависимости от ситуации.
Кэшированием можно управлять используя следующие HTTP заголовки:
- Date — дата и время создания ресурса.
- Last Modified — дата и время последнего изменения ресурса на сервере.
- Cache-Control — заголовок HTTP 1.1 используемый для управления кэшированием.
- Age — время, прошедшее с момента последнего получения ресурса, заголовок может быть добавлен промежуточным (между клиентом и сервером) компонентом (например, прокси сервер).
Рекомендации по кэшированию:
- Рекомендуется кэшировать статические ресурсы, такие как изображения, стили css, файлы javascript.
- Не рекомендуется указывать большое время жизни кэша.
- Динамическое содержимое должно кэшироваться на короткое время или не кэшироваться вообще.
Общие рекомендации
Тип представления ресурса
Хотя REST не накладывает явных ограничений на формат, который должен быть использован для представления ресурсов, наиболее популярными являются XML и JSON.
Существует множество библиотек в разных языках программирования для удобной работы с этими форматами. Несмотря на это, рекомендуется использовать именно JSON для представления ресурсов. Это более лёгкий, читабельный формат, с которым проще работать по сравнению с XML, а также проще выполнять сериализацию/десериализацию объектов в различных языках программирования.
Однако иногда для поддержки некоторых REST клиентов сервису необходимо поддерживать XML формат. В таком случае можно реализовать поддержку обоих форматов и указывать в параметре запроса, в каком формате должен быть представлен ответ.
Использование проверенных решений для авторизации
Используйте для авторизации проверенные и отработанные схемы.
Не изобретайте свой велосипед с использованием md5 подписей данных и прочего, доверьтесь профессионалам в области защиты данных. Всё уже придумано за вас: OAuth, OpenID, APIKeys.
Обработка исключений
При возникновении ошибочных ситуаций необходимо выводить отформатированную и понятную информацию. Это относится в первую очередь к статус коду в HTTP ответе. Ошибки в сервисах чаще всего относятся к двум типам:
- 4xx — ошибки клиента;
- 5xx — ошибки сервера.
В случае ошибки клиента, например, ошибки валидации какого-то из параметров запроса, в теле ответа рекомендуется передавать полезную информацию об ошибке: сообщение, описание, код (например, в формате JSON). В случае ошибки сервера отправлять дополнительную информацию в теле ответа не всегда возможно, например, в случаях, когда сервер недоступен.
Плохим тоном является вывод всего стэк трейса исключения. Рекомендуется для каждой исключительной ситуации иметь свой код. В дальнейшем при выводе информации об ошибке можно будет добавить ссылку на документацию, в которой данный код будет выступать уникальным идентификатором.
Например:
Полезные ссылки
-
- https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
- https://medium.com/@mwaysolutions/10-best-practices-for-better-restful-api-cbe81b06f291
- https://habr.com/ru/post/144011/
- https://habr.com/ru/post/144259/