Коды состояний HTTP — (REST API в WordPress → Базовые знания REST API)


Содержание материала:

Примеры запросов в REST API

Группы пользователей

Для добавления новой группы пользователей необходимо сформировать POST запрос по адресу:

В теле запроса необходимо заполнить основную информацию по группе:

id — уникальный идентификатор группы

name — отображаемое имя группы

documentTypeNames- список типов документов, к которым имеют доступ пользователи этой группы

Если группа существует, то данные его обновятся.

Для обновления отдельных полей можно использовать PATCH запрос по адресу с указанием идентификатора:

вместо необходимо вставить идентификатор обновляемой записи.

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

В результате у записи с указанным идентификатором обновится только одно поле «name»

Для получения списка всех групп необходимо сформировать GET запрос по адресу:

В результате получим список всех групп со всей информацией по ним

В данном запросе можно использовать все виды фильтрации, поддерживаемыми Odata. Например, если нужно вывести только группы, привязанных к типу документа “Заказ”, формируем такой запрос

Если необходимо дополнительно видеть всех пользователей в списке групп, то нужно сформировать запрос так:

В результате получим список групп с пользователями

для получения конкретной группы нужно вызвать GET запрос:

вместо необходимо вставить идентификатор обновляемой записи.

для получения группы с пользователями:

для получения только пользователей, относящихся к этой группе:

Пользователи

Для добавления нового пользователя или редактирования существующего необходимо сформировать POST запрос по адресу:

В теле запроса необходимо заполнить основную информацию по пользователю:

id — уникальный идентификатор пользователя

name — отображаемое имя пользователя

password — пароль пользователя

barcode — штрихкод для быстрого входа пользователя на терминале

groupId — определяет к какой группе относится пользователь

warehouseIds — определяет к каким складам относится пользователь

Если пользователь существует, то данные его обновятся.

Для обновления отдельных полей пользователя можно использовать PATCH запрос по адресу с указанием идентификатора:

вместо необходимо вставить идентификатор обновляемой записи.

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

В результате у записи с указанным идентификатором обновится только одно поле «name»

Для получения списка всех пользователей необходимо сформировать GET запрос по адресу:

В результате получим список всех пользователей со всей информацией по ним

В данном запросе можно использовать все виды фильтрации, поддерживаемыми Odata. Например, если нужно вывести только пользователей, привязанных к складу “1”, формируем такой запрос

Если необходимо отобрать всех пользователей относящихся к группе “общая”, формируем запрос:

Таблицы

Для добавления новой строки в таблицу необходимо сформировать POST запрос по адресу:

Например если нужно обновить таблицу Контрагентов:

В теле запроса необходимо заполнить основную информацию по группе:

uid- уникальный идентификатор строки

index- индекс строки

field1,field2 … -поля, которые необходимо сохранить в строке

Если строка существует, то данные ее обновятся.

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

Для удаления строки нужно сформировать DELETE запрос с указание uid строки:

Номенклатура

Для добавления новой строки в таблицу номенклатуры необходимо сформировать POST запрос по адресу:

В теле запроса необходимо заполнить основную информацию по группе:

id — уникальный идентификатор строки

name — наименование товара

barcode- штрихкод товара

field1,field2 … -поля, которые необходимо сохранить в строке

Если строка существует, то данные ее обновятся.

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

Для удаления строки нужно сформировать DELETE запрос с указание id строки:

Документы

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

Список документов также поддерживает параметры для порционной загрузки, которые передаются в виде query-строки(?$top=1&$skip=10)

При выполнении данного запроса мы получим максимум 5 записей начиная с 11 индекса в списке.

Если в запросе на получение списка указать параметр count=true, в результате вернется дополнительно поле count, которое содержит общее число записей в списке на сервере.

Для фильтрации данных в запросе можно указывать параметр $filter, например:

При выполнении данного запросы мы получим список документов, дата изменения которых более указанной в запросе и тип документа — “Заказ”.

Также можно указывать список полей, которые необходимо отобразить в результате, например:

Результатом выполнения данного запроса будет список документов, состоящих только из 2-х полей — id и tables

Для получения нужной записи необходимо составить запрос с указанием идентификатора этой записи, например:

Чтобы отсортировать результат необходимо указать параметр $orderby, например:

В результате получим список документов, отсортированный по идентификатору

Для документов реализован вывод записей строк документа и таблиц документа

Если в документе с идентификатором “1” существует таблица “ОплатыВозвраты”, то получить строки таблицы можно отправив запрос:

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

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

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

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

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

Введение в REST API

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

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

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

В этом примере мы используем консольную утилиту 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& >где параметр

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

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

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

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

Копирование материалов разрешается только с указанием автора (Михаил Русаков) и индексируемой прямой ссылкой на сайт (http://myrusakov.ru)!

Добавляйтесь ко мне в друзья ВКонтакте: http://vk.com/myrusakov.
Если Вы хотите дать оценку мне и моей работе, то напишите её в моей группе: http://vk.com/rusakovmy.

Если Вы не хотите пропустить новые материалы на сайте,
то Вы можете подписаться на обновления: Подписаться на обновления

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

Порекомендуйте эту статью друзьям:

Если Вам понравился сайт, то разместите ссылку на него (у себя на сайте, на форуме, в контакте):

Она выглядит вот так:

  • BB-код ссылки для форумов (например, можете поставить её в подписи):
  • Комментарии ( 0 ):

    Для добавления комментариев надо войти в систему.
    Если Вы ещё не зарегистрированы на сайте, то сначала зарегистрируйтесь.

    Copyright © 2010-2020 Русаков Михаил Юрьевич. Все права защищены.

    WordPress REST API — для чего и что это такое?

    Сегодня мы поговорим о WordPress REST API (некоторые называют его JSON REST API), грядущем дополнении к ядру WordPress, которое сейчас доступно в виде плагина и изначально появилось в версии 4.1. Сейчас же нас ждет двухступенчатая интеграция в версиях 4.4 и 4.5. Если разработчики очень восторженно относятся к появлению этой новой функции, то среднестатистический пользователь WordPress может не понять всего этого восторга, хотя появление данной функции можно назвать знаковой вехой в истории WordPress. Давайте же узнаем, что такое WordPress REST API, и что его появление означает для будущего WordPress, а также, почему это пишется заглавными буквами.

    Что такое API?

    Давайте начнем с базовых вещей и терминологии, так как название JSON REST API полностью составлено из акронимов. Первые три буквы “API” – это Application Programming Interface (интерфейс программирования приложений).

    Для чего нужен API?

    Базово API нужен для соединения разных элементов программного обеспечения, и вы можете воспринимать его, как USB-порт.

    USB-порты используются для связи различных типов девайсов с вашим компьютером. Это могут быть принтеры, элементы управления компьютером, портативные жесткие диски, телефоны и т.д. Через данный порт компьютер и девайс могут взаимодействовать друг с другом, обмениваясь информацией. API – это что-то похожее, только он связывает не девайсы, а программы. Таким образом, программы могут обмениваться данными в строго оговоренных рамках, взаимодействуя друг с другом. Вы постоянно используете API, даже не замечая этого. Например, если вы используете сторонние программы, чтоб воспользоваться своим аккаунтом в Twitter, то это действие выполняется посредством Twitter API. Благодаря API-технологии, я могу находиться в Twitter каждый день, даже не заходя на Twitter-сайт.

    API также необходим, когда вы используете сервисы email-маркетинга, типа MailChimp, на своем WordPress-сайте. Если говорить коротко, то интерфейс программирования приложений позволяет разработчикам использовать функции и данные других веб-приложений или сервисов для своего собственного программного обеспечения в совершенно безопасном русле.

    Что значит REST и JSON?

    REST — это сокращение от английского Representational State Transfer (передача состояния представления). REST описывает определенную архитектуру API, разработанную таким образом, чтоб он был легковесным, дружественным к пользователю и подходящим для широкого спектра сервисов. Google, Facebook и Twitter используют REST-стиль для многих своих API, по той простой причине, что REST создан на основе HTTP – протокола, который повсеместно используется в сети, вместе со своим более безопасным кузеном HTTPS. Благодаря своей высокой совместимости с современными технологиями, API, созданные на базе REST, набирают все большую популярность в сети, и не только в случае WordPress. Практически любая программа, которая имеет доступ в интернет, может использовать этот тип API. Похоже, это несет большие возможности для взаимодействия программ, не так ли?

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

    Формат JSON может стать чем-то вроде универсального соединительного звена на просторах интернета, и по этой причине WordPress и другие крупные сервисы решили воспользоваться этим преимуществом. Вдобавок ко всему, в WordPress JSON также заменяет немного устаревший XML-RPC-стандарт, который более сложен в использовании.

    Под всем сказанным можно сделать следующие выводы:

    • API — это разъем на любом программном обеспечении;
    • REST – это дизайн данного разъема;
    • JSON – это кабель с универсальными вилками на концах;

    JSON REST API и WORDPRESS

    Ладно, мы поняли, что штука эта — полезная. Но разве WordPress уже не использует эти API в своей структуре? Ну да, один есть, и это — WordPress API. Используется он для WordPress-плагинов, и работает только с внутренними процессами WordPress. Но если мы говорим о взаимодействии с программным обеспечением извне, то этот API – устарел и не очень дружественен к пользователю. Новый WP API гораздо более универсален, так как создан для того, чтоб, WordPress мог с легкостью взаимодействовать с другими веб-сайтами и сервисами в интернете. С помощью универсального API можно отображать и сохранять контент с других сайтов и приложений, не зависимо от того, используется ли там движок WordPress или нет. Все верно, данный API позволяет платформе WordPress стать системой управления контентом, подходящей для любого приложения, написанного на любом языке.

    Плюс, тоже самое работает и в обратном порядке. Все, что есть на вашем WordPress-сайте, будет также доступно и на любом внешнем веб-сайте и сервисе, включая:

    • Записи;
    • Страницы;
    • Пользовательские типы записей;
    • Медиа;
    • Комментарии;
    • Таксономии;
    • Пользователи;
    • И многое другое

    Это работает, потому что в основе всего лежит HTTP, который доступен везде. Протокол позволяет сайтам посылать, создавать, читать, обновлять или удалять запросы между двумя сторонами. В HTTP команды POST, GET, PUT, и DELETE являются эквивалентами. Кроме того, API понимает URLы, структура которых похожа на директории, а как мы знаем, похожие ссылки как раз использует WordPress и другие системы управления контентом.

    Суммируя сказанное, моно сказать, что если вы захотите перенести все записи определенного пользователя с вашего сайта на другой ресурс, то вы можете просто воспользоваться директивой —

    Тоже самое касается и обновления единичных записей, удаления пользователей, публикации страниц и многого другого. Если коротко, то API позволяет вам управлять административной областью WordPress, без необходимости ручной авторизации и использовать контент, не принадлежащий WordPress.

    Здорово, но безопасно ли это? Хорошая новость заключается в том, что WordPress REST API имеет встроенные меры безопасности. Волшебное слово здесь – это аутентификация. У интерфейса есть и куки-аутентификация, и OAuth-аутентификация. Таким образом, куки-аутентификация работает для плагинов и тем, а OAuth используется для аутентификации мобильных и веб-клиентов, а также клиентов настольных компьютеров. Оба метода лимитируют сторонние действия на вашем сайте. Так как API созданы для того, чтоб платформы могли лимитировано обмениваться строго определенной информацией, то ваши данные в полной безопасности.

    Что значит WP API для WORDPRESS?

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

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

    • Любой разработчик может создать альтернативную WordPress админ-панель фактически на основе любого девайса или платформы.
    • Новый API может привнести множество альтернатив стандартному бэкенду, включая мобильные приложения, доступные для администрирования WordPress
    • Так как поддержка JSON изначально встроена в iOS и Android, то монополия WordPress-приложений станет историей.
    • Сторонний контент также будет доступен WordPress. И даже более того, API делает WordPress-контент независимым от языка программирования и среды, так что вы можете брать материалы из любого источника и отображать их, как захотите.
    • Ruby on Rails и другие фреймворки получат доступ к функциональности WordPress со всеми вытекающими из этого возможностями, и преимущества этих областей станут доступны для WordPress-пользователей.

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

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

    WordPress входит в новую эру

    WordPress не только станут доступны новые типы контента, но благодаря новому API и контент WordPress станет доступен всему интернету. Системы, построенные не на основе PHP, смогут использовать данные WordPress, адаптируя их с помощью собственных приложений.

    Но интереснее всего звучит возможность использования WordPress-продуктов, к примеру, плагинов, на других платформах, и системах управления контентом.

    Мобильные приложения, созданные на базе WordPress, будут доступны повсеместно, что является прекрасной новостью для всех тех, кто их создает или использует. Я думаю, что появятся решения, которые позволят обычному пользователю автоматически создавать мобильные приложения на базе WordPress-сайтов.

    В итоге:

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

    Как использовать REST API WordPress

    Divi: самая простая тема WordPress для использования

    Divi: Лучшая тема WordPress всех времен!

    Более Загрузка 600.000, Divi — самая популярная тема WordPress в мире. Он является полным, простым в использовании и поставляется с более чем бесплатными шаблонами 62. [Рекомендуется]

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

    Сегодня преобразование продолжается с приходом WordPress REST API.

    В этом руководстве я объясню, что такое API-интерфейс WordPress REST, и покажу, как его использовать.

    Но раньше, если вы никогда не устанавливали WordPress, откройте для себя Как установить WordPress блог шаги 7 et Как найти, установить и активировать WordPress тему на своем блоге

    Тогда давайте вернемся к тому, почему мы здесь

    Что такое REST API

    Для простоты, поймите, что REST API WordPress, позволяет взаимодействовать с ядром WordPress без прохождения через его графический интерфейс. Это означает разделение ядра и GUI. С помощью этого API, например, вы можете создать новую статью, не имея доступа к приборная панель, REST API будет включен в ядро ​​при выпуске версии 4.4 к декабрю.

    Учитывая характер предмета этого урока, необходимо хорошее знание PHP и WordPress.

    Что нам нужно для этого урока

    Для того, чтобы начать с REST API, вам понадобится плагин REST API а также последняя версия WordPress. У тебя это есть? Если нет, понять, почему. Представления об HTTP API WordPress также будут хорошими компаниями для удаленных звонков.

    В качестве проекта для этого урока мы создаст локальную установку WordPress из которого мы будем получать статьи с нашего сайта через REST API. Убедитесь, что на рабочем сайте установлен и активирован подключаемый модуль REST API.

    Теперь создайте виджет в вашей локальной установке. Вот основной код:

    / **
    * Имя плагина: REST API Test Widget
    * Плагин URI: http://the-site-of-your-widget-ici.com
    * Описание: этот виджет извлекает статьи, используя REST API
    * Версия: 1.0
    * Автор: Ваше имя
    * Авторский URI: http://your-site.com
    */

    Mes_Articles_Widget класс расширяет


    public function __construct () <
    $ w >
    ‘classname’ => ‘widget-test-rest-api’,
    ‘description’ => ‘Виджет, который получает статьи с помощью REST API с другого сайта’
    );

    parent :: __ construct (‘widget-test-rest-api’, ‘REST API Trial Widget’, $ widget_details);

    форма публичной функции ($ instance) <
    $ title = (! empty ($ instance [‘title’]))? $ instance [‘title’]: »;
    >

    get_field_name (‘title’);?>»> Название:
    get_field_id (‘title’);?>» name = » get_field_name (‘title’);?>» type = «text» value = » » />

    >
    общественные функции виджет ($ арг, $ экземпляра) <
    echo $ args [‘before_widget’];
    if (! empty ($ instance [‘title’])) <
    echo $ args [‘before_title’]. apply_filters (‘widget_title’, $ instance [‘title’], $ instance, $ this-> base_id). $ Args [ ‘after_title’];
    >
    // функциональный код виджета здесь
    echo $ args [‘after_widget’];
    >
    >
    add_action ( ‘widgets_init’, функция () <
    register_widget (‘My_Articles_Widget’);
    >);

    В каталоге плагинов вашего локального сайта создайте папку с именем виджет-тест-отдых-апи. В этой папке создайте файл с именем виджет-тест-отдых-api.php и вставьте код выше.

    Этот код содержит заголовок расширений (комментарии в начале кода), который позволяет WordPress знать, что это расширение. Затем следует минимальный код создания виджета, увеличенный на несколько строк.

    Мы уделим больше внимания функции виджет ()потому что внутри него построено отображение виджета. Поэтому именно в этой функции мы будем выполнять вызовы, используя HTTP API.

    Получить статьи

    Нам потребуется некоторая информация для запроса производственного веб-сайта или веб-сайта в Интернете. Это будет так или иначе вопрос, заданный ядром WordPress нашего онлайн-сайта. Это базовый путь API, используемый маршрут, используемый терминатор, заголовки и параметры.

    Сублимируйте свои иллюстративные изображения, обнаруживая Как создавать интерактивные изображения в блоге WordPress

    Базовый путь REST API WordPress всегда / Wp-JSON / в.ч. / v2 /, Таким образом, полный путь будет http://votre-domaine.com/wp-json/wp/v2/.

    Маршрут, используемый для получения предметов / сообщений, Что делает полный маршрут для статей http://votre-domaine.com/wp-json/wp/v2/posts.

    Каждый маршрут может иметь несколько концовок, различающихся по используемому методу HTTP. Таким образом, дорога к статье может быть / Сообщений / 291. Это дорога 3 окончания:

    ПОЛУЧИТЬ : чтобы получить статью
    ПОЛОЖИЛ : обновить статью
    УДАЛИТЬ : удалить статью.

    Вы ищете лучшие темы и плагины WordPress?

    Загрузите лучшие плагины и темы WordPress на Envato и легко создайте свой сайт. Уже больше, чем 49.720.000. [ЭКСКЛЮЗИВ]

    Создаем наш первый API при помощи Node.js и Express: Разбираемся с REST API

    Russian (Pусский) translation by AlexBioJS (you can also view the original English article)

    Разбираемся с REST и RESTful API

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

    В этой серии мы начнем с обзора принципов и понятий REST. Затем мы приступим к созданию нашего собственного полностью работоспособного API, который работает на основе сервера, созданного при помощи Express и Node.js, и подключается к базе данных MySQL. После изучения руководств этой серии вы должны будете чувствовать себя уверенно при создании вашего собственного API или при работе с документацией уже существующего.

    Предварительная подготовка

    Для того чтобы получить от этого руководства максимум пользы, вы уже должны иметь базовые навыки работы с командной строкой, обладать базовыми знаниями по JavaScript и иметь на своем компьютере установленную глобально Node.js.

    Что из себя представляют REST и RESTful API?

    При помощи Representational State Transfer (* передача репрезентативного состояния), или REST, описывается архитектурный стиль для веб-сервисов. REST состоит из ряда стандартов или ограничивающих требований по обмену данными между различными системами, и для систем, которые работают согласно принципам REST, используется термин RESTful. REST – абстрактная концепция, это не язык, не фреймворк или тип программного обеспечения.

    Для лучшего понимания REST вам могла бы помочь аналогия, когда сравнивается коллекция виниловых пластинок с сервисом для потоковой передачи аудио-данных (* способ воспроизведения аудио- и видеоматериалов из интернета без их предварительного скачивания в компьютер). В случае с виниловыми пластинками для их распространения необходимо, чтобы для каждой записи была создана полная копия. В случае же с сервисом для потоковой передачи аудио-данных та же самая музыка может распространяться неограниченный срок, если известны какие-либо данные, например название песни. В этом случае сервис для потоковой передачи аудио-данных является RESTful сервисом, а коллекция виниловых пластинок – нет.

    API (Application Programming Interface) – интерфейс, который позволяет программам общаться друг с другом. RESTful API – просто API, который работает согласно принципам и понятиям REST. В случае с API, работающим в сети, сервер получает запрос при помощи конечной точки, где указан URL-адрес, и отправляет обратно ответ, которым часто являются данные в формате вроде JSON.

    Принципы REST

    К архитектуре REST выдвигаются шесть основных требований, перечисленных ниже:

    1. Унифицированный интерфейс: интерфейс компонентов должен быть одинаковым. Это достигается за счет использования стандарта URI для идентификации ресурсов – другими словами, путей, которые могли бы быть набраны в адресной строке браузера.
    2. Клиент-Сервер: сервер и клиент выполняют различные задачи: сервер хранит данные и выполняет с ними манипуляции, а клиент отправляет запросы и отображает ответы.
    3. Взаимодействия без запоминания состояния: вся информация о каждом запросе содержится в нем самом и не зависит от состояния сессии.
    4. Возможность использования кэш-памяти: клиент и сервер могут кэшировать ресурсы.
    5. Многоуровневая система: клиент может подключаться к конечному серверу или промежуточному слою вроде компенсатора (* инструмент для эффективного распределения приходящего к группе серверов траффика).
    6. Получение кода по запросу (Не обязательно): клиент может скачать код, за счет чего снижается его видимость в сети.

    Запрос и ответ

    Вы в курсе, что для всех веб-сайтов используется URL, который начинается с http (или https в случае использования безопасной версии протокола). HyperText Transfer Protocol, или HTTP, – метод коммуникации клиентов с серверами в Интернете.

    Нам наиболее очевидно его существование, когда мы вводим в адресных строках наших браузеров URL-адреса, однако HTTP может использоваться не только для запрашивания веб-сайтов с серверов. Когда вы переходите по адресу URL, то, собственно, выполняете запрос по методу GET для получения определенного ресурса, и веб-сайт, который вы видите, является телом ответа. Мы скоро рассмотрим запросы, выполняющиеся по методу GET и другим.

    HTTP работает путем открытия соединения TCP (Transmission Control Protocol – протокол управления передачей) к порту сервера ( 80 для http , 443 для https ) для выполнения запроса, а прослушивающий запросы сервер отправляет ответы, в которых содержатся код ответа и тело.

    Ответ должен состоять из URL, метода, информации заголовка и тела.

    Методы запроса

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

    Методы запроса HTTP приблизительно соответствуют парадигме CRUD, что расшифровывается как Create, Update, Read, Delete (* создать, прочесть, обновить, удалить). Хотя CRUD относится к функциям, используемым при выполнении операций над базой данных, мы можем применить те основы конструирования к глаголам HTTP в RESTful API.

    Действие Метод запроса Определение
    Прочитать GET При помощи него выполняется получение ресурса
    Создать POST При помощи него выполняется создание нового ресурса
    Обновить PUT При помощи него выполняется обновление существующего ресурса
    Удалить DELETE При помощи него выполняется удаление ресурса

    GET – безопасная операция, которая используется только для считывания данных и при выполнении которой состояние сервера не изменится. Каждый раз, когда вы вводите в вашем браузере URL-адрес, например https://www.google.com , вы отправляете запрос по методу GET к серверам Google.

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

    При помощи метода PUT существующий ресурс обновляется, что могло бы быть использовано для редактирования настроек существующего пользователя. В отличие от POST PUT – идемпотентный метод. Это означает, что при повторном выполнении запроса будет получаться тот же самый результат. Например если бы вы отправили тот же самый запрос по методу POST для создания нового пользователя в базе данных множество раз, то в результате был бы создан новый пользователь с теми же данными. Однако в результате выполнения того же запроса по методу PUT для того же самого пользователя неизменно выходил бы одинаковый результат.

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

    Коды ответа

    Как только запрос поступит на сервер, тот отправит ответ HTTP, в котором будут содержаться метаданные об ответе (заголовки) и тело. Первая и наиболее важная часть ответа – код состояния, который указывает на то, был ли запрос выполнен успешно, была ли совершена ошибка при его обработке или же на то, что должно быть выполнено иное действие.

    Наиболее известным кодом ответа для вас должен быть 404 , что означает Not Found (* сообщает, что запрашиваемый ресурс не существует на сервере). 404 входит в состав класса 4xx кодов состояния, при помощи которых указывается, что при обработке запроса произошла ошибка. Имеется пять классов кодов состояния, в каждом из которых имеется ряд кодов.

    • 1xx : Information (* Информация о процессе передачи)
    • 2xx : Success (* Информация об успешном принятии и обработке запроса клиента)
    • 3xx : Redirection (* Перенаправление)
    • 4xx : Client Error (* Информация об ошибках со стороны клиента)
    • 5xx : Server Error (* Информация об ошибках со стороны сервера)

    Другими распространенными кодами ответов, с которыми вы, скорее всего, знакомы, являются 301 Moved Permanently , который используется для перенаправления браузера по другому URL-адресу, и 500 Internal Server Error , что указывает на то, что при обработке запроса произошла непредвиденная ошибка на стороне сервера, из-за чего текущий запрос не может быть выполнен.

    Что касается API RESTful и их соответственных глаголов HTTP, то коды всех ответов должны находиться в диапазоне 2xx .

    Запрос Ответ
    GET 200 (OK)
    POST 201 (Created) (* Создано)
    PUT 200 (OK)
    DELETE 200 (OK), 202 (Accepted) (* Принято) или 204 (No Content) (* Нет содержимого; тело сообщения не передается)

    200 OK – код ответа, который указывает на то, что запрос был выполнен успешно. Он используется в качестве кода ответа при отправлении запроса по методу GET или PUT . При выполнении запросов по методу POST будет возвращен ответ с кодом состояния 201 Created для указания того, что новый ресурс был создан, и при выполнении запросов по методу DELETE возможны несколько вариантов кодов ответа, благодаря которым подтверждается, что либо запрос был успешно принят ( 202 ), либо отправлять нечего, поскольку ресурс более не существует ( 204 ).

    Мы можем протестировать код состояния ответа на запрос ресурса при помощи cURL – инструмента командной строки, который используется для передачи данных при помощи URL-адресов. При помощи команды curl , за которой следует флажок -i или —include будет отправлен запрос по методу GET по указанному URL-адресу и отображены заголовки и тело. Мы можем протестировать это, если откроем консоль и отправим запросы к Google.

    Сервера Google пришлют ответ со следующей информацией:

    Как видно, в ответ на запрос curl было отправлено множество заголовков и все тело HTML-ответа. Поскольку запрос был выполнен успешно, то первой частью ответа является код состояния 200 вместе с версией HTTP (ею может быть либо HTTP/1.1, либо HTTP/2).

    Поскольку в ответ на этот конкретный запрос в ответе приходит веб-сайт, то в качестве значения заголовка content-type (тип MIME (* Multipurpose Internet Mail Extensions – многоцелевые расширения почты (почтовой службы)) указывается text/html . В RESTful API вы, скорее всего, увидите вместо этого application/json , что указывает на то, что форматом ответа является JSON.

    Интересно то, что мы можем увидеть иной тип ответа, слегка изменив вводимый URL-адрес. Выполните команду curl для отправления запроса к Google без www .

    Google перенаправит клиент на www.google.com , и в ответе будет прислан код состояния 301 для указания того, что должно быть выполнено перенаправление.

    Конечные точки RESTful API

    Когда API располагается на сервере, то предоставляемые им данные доступны при помощи конечных точек. Конечная точка – отдельная функция API, которая запускается при обращении к серверу по определенному URL-адресу и может принимать и обрабатывать запросы по методу GET , POST , PUT или DELETE .

    URL API будет состоять из корня, пути и необязательной строки запроса.

    • Корень, например https://api.example.com или https://api.example.com/v2 , – корень URL, который может состоять из протокола, домена и версии протокола.
    • Путь, например /users/ или /users/5 , – уникальное местоположение определенного ресурса.
    • Параметры запроса (указывать необязательно), например ?location=chicago&age=29 , – необязательные пары ключ=значение, которые используются для сортировки, фильтрации и разбиения контента на страницы.
      Мы можем собрать эти компоненты воедино для получения нечто подобного тому, что показано в примере ниже, благодаря чему был бы возвращен список всех пользователей и использован параметр запроса limit для того, чтобы в результате фильтрации в ответ были включены только 10 результатов.

    Обычно, когда люди ссылаются на API как на RESTful API, они имеют ввиду соглашения о названиях, которые используются для построения URL конечной точки API. Несколько важных соглашений для стандартного RESTful API представлены ниже:

    • Названия путей должны быть указаны во множественном числе: например для того чтобы получить данные о пользователе с id 5 , мы бы воспользовались /users/5 , а не /user/5 .
    • В URL не должно содержаться расширения файла: несмотря на то что при обращении к конечной точке API, скорее всего, будет возвращаться файл в формате JSON, URL не должен оканчиваться на .json .
    • В URL должны использоваться существительные, а не глаголы: слова вроде add и delete не должны содержаться в URL, используемом в RESTful API. Для добавления нового пользователя вы могли бы просто отправить POST -запрос по адресу, в котором используется /users , а не что-то вроде /users/add . API должен разрабатываться так, чтобы был способен обрабатывать различные типы запросов по тому же самому URL-адресу.
    • Пути чувствительны к регистру (заглавным или строчным буквам) и должны быть написаны в нижнем регистре с использованием дефисов, а не символов подчеркивания.

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

    Как правильно работать с REST API

    Коротко обо мне

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

    Вступление

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

    В данной статье вы узнаете все о REST API для того, чтобы работать с ними и читать связанную с ними документацию.

    Что же такое REST API?

    Давайте представим, что вы пытаетесь найти фильмы о Бэтмене на YouTube. Вы открываете сайт, вбиваете в форму поиска слово «Бэтмен», жмакаете «Окей» и видите список фильмов о супергерое. Похожим образом работает и WEB API. Вы ищите что-то и получаете список результатов от запрашиваемого ресурса.

    Дословно API расшифровывается как Application Programming Interface. Это набор правил, позволяющий программам «общаться» друг с другом. Разработчик создает API на сервере и позволяет клиентам обращаться к нему.

    REST – это архитектурный подход, определяющий, как API должны выглядеть. Читается как «Representational State Transfer». Этому набору правил и следует разработчик при создании своего приложения. Одно из этих правил гласит, что при обращении к определенному адресу, вы должны получать определенный набор данных (ресурс).

    Каждый адрес маршрутом, пакет данных — запросом, в то время как результатирующий ресурс – ответом.

    Анатомия запроса

    Важно понимать структуру запроса:

    1. Маршрут отправки
    2. Тип метода
    3. Заголовки
    4. Тело (или данные)

    Маршрут – это адрес, по которому отправляется ваш запрос. Его структура примерно следующая:

    Root-endpoint — это точка приема запроса на стороне сервера (API). К примеру, конечная точка GitHub – https://api.github.com.

    Путь определяет запрашиваемый ресурс. Это что-то вроде автоответчика, который просит вас нажать 1 для одного сервиса, 2 для другого и так далее.

    Для понимания того, какие именно пути вам доступны, вам следует просмотреть документацию. К примеру, предположим, вы хотите получить список репозиториев для конкретного пользователя на Git. Согласно документации, вы можете использовать следующий путь для этого:

    Вам следует подставить под пропуск имя пользователя. К примеру, чтобы найти список моих репозиториев, вы можете использовать маршрут:

    Последняя часть маршрута – это параметры запроса. Технически запросы не являются частью REST-архитектуры, но на практике сейчас все строится на них. Так что давайте поговорим о них более детально. Параметры запроса позволяют использовать в запросе наборы пар «ключ-значение». Они всегда начинаются знаком вопроса. Каждая пара параметров после чего разделяется амперсантом (что-то вроде этого):

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

    Если же вы желаете получить список моих недавно запушеных репозиториев, вам следует ввести следующее:

    Итак, как же понять, что маршруты рабочие? Что ж, пришло время проверить их на практике!

    Тестирование при помощи Curl

    Вы моете отправить запрос при помощи любого языка программирования. JavaScript может использовать методы вроде Fetch API или JQuery`s Ajax Method. Руби использует другое. И так далее.

    В этой статье я буду использовать такую утилитку, как Curl. Дело в том, что она указана в официальной документации для веб-сервисов. Если вы поймете, как использовать эту утилиту, вы поймете, как работать с API. После чего вы можете производить запросы любым удобным для вас языком.

    Перед тем, как продолжить, вам следует убедится, что Curl установлен на вашей машине.

    Ели же он не установлен, самое время установить. В таком случае вы получите ошибку «command not found».

    Для того, чтобы использовать утилиту, необходимо ввести следующее (по примеру):

    И как только вы подтверждаете ввод, вы получаете ответ (наподобие этого):

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

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

    Также попробуйте другие команды и произведите запросы! В результате вы получаете похожие ответы.

    JSON

    JSON – JavaScript Object Notation – общий формат для отправки и приема данных посредством REST API. Ответ, отправляемый Github, также содержится в формате JSON.

    Содержание объекта этого формата примерно следующее:

    Возвращаемся к анатомии запроса

    Вы изучили, что запрос состоит из четырех частей:

    1. Маршрут отправки
    2. Тип метода
    3. Заголовки
    4. Тело (или данные)

    Теперь же давайте попробуем разобраться с остальным.

    Тип метода

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

    GET – используется для получения со стороны севера определенного ресурса. Если вы производите этот запрос, сервер ищет информацию и отправляет ее вам назад. По сути, он производит операцию чтения на сервере. Дефолтный тип запросов.

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

    PUT и PATCH – используются для обновления определенной информации на сервере. В таком случае сервер просто изменяет информацию существующих сущностей в базе данных и оповещает об успехе выполнения операции.

    DELETE – как и следует из названия, удаляет указанную сущность из базы или сигнализирует об ошибке, если такой сущности в базе не было.

    Сам же API позволяет указать, какой метод должен быть использован в определенных контекстных ситуациях.

    GET запрос в этом случае необходим, чтобы получить список всех репозиториев указанного пользователя. Также можно использовать curl:

    Попробуйте отправить этот запрос. В качестве ответа вы получите требование об аутентификации.

    Заголовки

    Заголовки используются, чтобы предоставить информацию как клиенту, так и серверу. Вообще, их можно использовать для много чего – пример – та же самая аутентификация и авторизация. Найти список доступных заголовком можно на официальной странице MDN.

    Заголовки представляют из себя пары ключей-значений. Пример:

    Также пример с использованием curl:

    (Примечание: заголовок Content-Type в случае Github для работы не является обязательным. Это всего лишь пример использования заголовка в запросе, ничего более.)

    Для просмотра отправленных заголовком можно использовать следующее:

    Здесь звездочка относится к дополнительной информации, предоставленной посредством curl. > относится к заголовкам запроса, а

    WordPress.org

    Chapters

    Topics

    The WordPress REST API provides an interface for applications to interact with your WordPress site by sending and receiving data as JSON (JavaScript Object Notation) objects. It is the foundation of the WordPress Block Editor, and can likewise enable your theme, plugin or custom application to present new, powerful interfaces for managing and publishing your site content.

    An API is an Application Programming Interface. REST, standing for “REpresentational State Transfer,” is a set of concepts for modeling and accessing your application’s data as interrelated objects and collections. The WordPress REST API provides REST endpoints (URLs) representing the posts, pages, taxonomies, and other built-in WordPress data types. Your application can send and receive JSON data to these endpoints to query, modify and create content on your site. JSON is an open standard data format that is lightweight and human-readable, and looks like Objects do in JavaScript. When you request content from or send content to the API, the response will also be returned in JSON. Because JSON is widely supported in many programming languages, developers can build WordPress applications in client-side JavaScript (like the block editor), as mobile apps, or as desktop or command line tools.

    Note: The REST API is just one of many APIs provided by WordPress. You can find the documentation on these additional APIs here.

    Why use the WordPress REST API # Why use the WordPress REST API

    WordPress already provides a rich set of tools and interfaces for building sites, and you should not feel pressured to use the REST API if your site is already working the way you expect. You do not need to use the REST API to build a WordPress theme or plugin.

    However, if you do wish to write your theme, plugin, or external application as a client-side JavaScript application, or a standalone program in a language other than PHP, then your application will need a structured way to access content within your WordPress site. Any programming language which can make HTTP requests and interpret JSON can use the REST API to interact with WordPress, from PHP, Node.js, Go, and Java, to Swift, Kotlin, and beyond.

    Using the WordPress REST API you can create a plugin to provide an entirely new admin experiences for WordPress, build a brand new interactive front-end experience, or bring your WordPress content into completely separate applications. Even if you’re using vanilla JavaScript or jQuery within a theme or plugin the REST API provides a more predictable and structured way to interact with your site’s content than admin-ajax , enabling you to spend less time accessing the data you need and more time creating better user experiences.

    If you want a structured, extensible, and simple way to get data in and out of WordPress, you probably want to use the REST API.

    For all of its simplicity the REST API can feel quite complex at first, so in this handbook we will attempt to break it down into smaller components to explain each part of the full puzzle.

    Key Concepts # Key Concepts

    To get started we will break down some of the key concepts and terms associated with the REST API: Routes & Endpoints, Requests, Responses, Schema, and Controller Classes. Each of these concepts play a crucial role in understanding, using, and extending the WordPress REST API, and each is explored in greater depth within this handbook.

    Routes & Endpoints # Routes & Endpoints

    In the context of the WordPress REST API a route is a URI which can be mapped to different HTTP methods. The mapping of an individual HTTP method to a route is known as an endpoint.

    As an example, if we make a GET request to the URI http://oursite.com/wp-json/ we are returned a JSON response showing what routes are available, and what endpoints are available within each route. /wp-json/ is a route, and when that route receives a GET request then that request is handled by the endpoint which displays what is known as the index for the WordPress REST API. The route wp-json/wp/v2/posts by contrast has a GET endpoint which returns a list of posts, but also a POST endpoint which accepts authenticated requests to create new posts.

    We will learn how to register our own routes and endpoints in the following sections.

    Note: If you are using non-pretty permalinks, you should pass the REST API route as a query string parameter. The route http://oursite.com/wp-json/ in the example above would hence be http://oursite.com/?rest_route=/ .

    If you get a 404 error when trying to access http://oursite.com/wp-json/ , consider enabling pretty permalinks or try using the rest_route parameter instead.

    Requests # Requests

    A REST API request is represented within WordPress by an instance of the WP_REST_Request class, which is used to store and retrieve information for the current request. A WP_REST_Request object is automatically generated when you make an HTTP request to a registered API route. The data specified in this object (derived from the route URI or the JSON payload sent as a part of the request) determines what response you will get back out of the API.

    Requests are usually submitted remotely via HTTP but may also be made internally from PHP within WordPress plugin or theme code. There are a lot of neat things you can do using this class, detailed further elsewhere in the handbook.

    Responses # Responses

    Responses are the data you get back from the API. The WP_REST_Response class provides a way to interact with the response data returned by endpoints. Responses return the requested data, or can also be used to return errors if something goes wrong while fulfilling the request.

    Schema # Schema

    Each endpoint requires a particular structure of input data, and returns data using a defined and predictable structure. Those data structures are defined in the API Schema. The schema structures API data and provides a comprehensive list of all of the properties the API can return and which input parameters it can accept. Well-defined schema also provides one layer of security within the API, as it enables us to validate and sanitize the requests being made to the API. The Schema section explores this large topic further.

    Controller ># Controller Classes

    Controller classes unify and coordinate all these various moving parts within a REST API response cycle. With a controller class you can manage the registration of routes & endpoints, handle requests, utilize schema, and generate API responses. A single class usually contains all of the logic for a given route, and a given route usually represents a specific type of data object within your WordPress site (like a custom post type or taxonomy).

    Next Steps # Next Steps

    Learn more about how to interact with API resources and query for specific data in the Using the REST API section.

    Once you’re comfortable with the default workings of the default routes and methods, discover how to add new data to the API or enhance and manipulate existing response objects in the Extending the REST API section.

    For a comprehensive overview of the resources and routes available by default, review the API reference.

    REST: простым языком

    (REpresentational State Transfer) — это архитектура, т.е. принципы построения распределенных гипермедиа систем, того что другими словами называется World Wide Web, включая универсальные способы обработки и передачи состояний ресурсов по HTTP

    Автор идеи и термина Рой Филдинг 2000г.

    REST на сегодняшний день практически вытеснил все остальные подходы, в том числе дизайн основанный на SOAP и WSDL

    Что нам дает REST подход

    • Масштабируемости взаимодействия компонентов системы (приложения)
    • Общность интерфейсов
    • Независимое внедрение компонентов
    • Промежуточные компоненты, снижающие задержку, усиливающие безопасность

    Когда использовать REST?

    • Когда есть ограничение пропускной способности соединения


    • Если необходимо кэшировать запросы

    • Если система предполагает значительное масштабирование

    • В сервисах, использующих AJAX

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

    • Отсутствие дополнительных внутренних прослоек, что означает передачу данных в том же виде, что и сами данные. Т.е. данные не оборачиваются в XML, как это делает SOAP и XML-RPC, не используется AMF, как это делает Flash и т.д. Просто отдаются сами данные.
    • Каждая единица информации ( ресурс) однозначно определяется URL — это значит, что URL по сути является первичным ключом для единицы данных. Причем совершенно не имеет значения, в каком формате находятся данные по адресу — это может быть и HTML, и jpeg, и документ Microsoft Word.
    • Как происходит управление информацией ресурса — это целиком и полностью основывается на протоколе передачи данных. Наиболее распространенный протокол конечно же HTTP. Для HTTP действие над данными задается с помощью методов : GET (получить), PUT (добавить, заменить), POST (добавить, изменить, удалить), DELETE (удалить). Таким образом, действия CRUD (Create-Read-Update-Delete) могут выполняться как со всеми 4-мя методами, так и только с помощью GET и POST.

    Что такое RESTful:

    Чтобы распределенная система считалась сконструированной по REST архитектуре (Restful), необходимо, чтобы она удовлетворяла следующим критериям:

    1. Client-Server. Система должна быть разделена на клиентов и на серверов. Разделение интерфейсов означает, что, например, клиенты не связаны с хранением данных, которое остается внутри каждого сервера, так что мобильность кода клиента улучшается. Серверы не связаны с интерфейсом пользователя или состоянием, так что серверы могут быть проще и масштабируемы. Серверы и клиенты могут быть заменяемы и разрабатываться независимо, пока интерфейс не изменяется.
    2. Stateless. Сервер не должен хранить какой-либо информации о клиентах. В запросе должна храниться вся необходимая информация для обработки запроса и если необходимо, идентификации клиента.
    3. Cache․ Каждый ответ должен быть отмечен является ли он кэшируемым или нет, для предотвращения повторного использования клиентами устаревших или некорректных данных в ответ на дальнейшие запросы.
    4. Uniform Interface. Единый интерфейс определяет интерфейс между клиентами и серверами. Это упрощает и отделяет архитектуру, которая позволяет каждой части развиваться самостоятельно.

    Четыре принципа единого интерфейса:

    • >В REST ресурсом является все то, чему можно дать имя. Например,пользователь, изображение, предмет (майка, голодная собака, текущая погода) и т.д. Каждый ресурс в REST должен быть идентифицирован посредством стабильного идентификатора, который не меняется при изменении состояния ресурса. Идентификатором в REST является URI.
    • Manipulation of resources through representations. (Манипуляции над ресурсами через представления). Представление в REST используется для выполнения действий над ресурсами. Представление ресурса представляет собой текущее или желаемое состояние ресурса. Например, если ресурсом является пользователь, то представлением может являться XML или HTML описание этого пользователя.
    • Self-descriptive messages (само-документируемые сообщения). Под само-описательностью имеется ввиду, что запрос и ответ должны хранить в себе всю необходимую информацию для их обработки. Не должны быть дополнительные сообщения или кэши для обработки одного запроса. Другими словами отсутствие состояния, сохраняемого между запросами к ресурсам. Это очень важно для масштабирования системы.
    • HATEOAS (hypermedia as the engine of application state). Статус ресурса передается через содержимое body, параметры строки запроса, заголовки запросов и запрашиваемый URI (имя ресурса). Это называется гипермедиа (или гиперссылки с гипертекстом). HATEOAS также означает, что, в случае необходимости ссылки могут содержатся в теле ответа (или заголовках) для поддержки URI , извлечения самого объекта или запрошенных объектов.

    5 . Layered System. В REST допускается разделить систему на иерархию слоев но с условием, что каждый компонент может видеть компоненты только непосредственно следующего слоя. Например, если вы вызывайте службу PayPal а он в свою очередь вызывает службу Visa, вы о вызове службы Visa ничего не должны знать.

    6. Code-On-Demand (опционально). В REST позволяется загрузка и выполнение кода или программы на стороне клиента.

    Серверы могут временно расширять или кастомизировать функционал клиента, передавая ему логику, которую он может исполнять. Например, это могут быть скомпилированные Java-апплеты или клиентские скрипты на Javascript

    Важно ! Сама архитектура REST не привязана к конкретным технологиям и протоколам, но в реалиях современного Веб, построение RESTful API почти всегда подразумевает использование HTTP и каких-либо распространенных форматов представления ресурсов, например JSON, или, менее популярного сегодня, XML.

    Идемпотентность

    С точки зрения RESTful-сервиса, операция (или вызов сервиса) идемпотентна тогда, когда клиенты могут делать один и тот же вызов неоднократно при одном и том же результате на сервере. Другими словами, создание большого количества идентичных запросов имеет такой же эффект, как и один запрос. Заметьте, что в то время, как идемпотентные операции производят один и тот же результат на сервере, ответ сам по себе может не быть тем же самым (например, состояние ресурса может измениться между запросами).

    Методы PUT и DELETE по определению идемпотентны. Тем не менее, есть один нюанс с методом DELETE. Проблема в том, что успешный DELETE-запрос возвращает статус 200 (OK) или 204 (No Content), но для последующих запросов будет все время возвращать 404 (Not Found), Состояние на сервере после каждого вызова DELETE то же самое, но ответы разные.

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

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

    HTTP методы для создания RESTful сервисов

    HTTP метод GET используется для получения (или чтения) представления ресурса. В случае “удачного” (или не содержащего ошибок) адреса, GET возвращается представление ресурса в формате XML или JSON в сочетании с кодом состояния HTTP 200 (OK). В случае наличия ошибок обычно возвращается код 404 (NOT FOUND) или 400 (BAD REQUEST).

    HTTP метод PUT обычно используется для предоставления возможности обновления ресурса. Тело запроса при отправке PUT-запроса к существующему ресурсу URI должно содержать обновленные данные оригинального ресурса (полностью, или только обновляемую часть).

    Для создания новых экземпляров ресурса предпочтительнее использование POST запроса. В данном случае, при создании экземпляра будет предоставлен корректный идентификатор экземпляра ресурса в возвращенных данных об экземпляре.

    При успешном обновлении посредством выполнения PUT запроса возвращается код 200 (или 204 если не был передан какой либо контент в теле ответа). PUT не безопасная операция, так как вследствии ее выполнения происходит модификация (или создание) экземпляров ресурса на стороне сервера, но этот метод идемпотентен. Другими словами, создание или обновление ресурса посредством отправки PUT запроса — ресурс не исчезнет, будет располагаться там же, где и был при первом обращении, а также, многократное выполнение одного и того же PUT запроса не изменит общего состояния системы

      PUThttp://www.example.com/api/v1.0/users/12345 (обновить данные пользователя с > PUThttp://www.example.com/api/v1.0/users/12345/orders/98765 (обновить данные заказа с > HTTP метод POST запрос наиболее часто используется для создания новых ресурсов. На практике он используется для создания вложенных ресурсов. Другими словами, при создании нового ресурса, POST запрос отправляется к родительскому ресурсу и, таким образом, сервис берет на себя ответственность на установление связи создаваемого ресурса с родительским ресурсом, назначение новому ресурсу ID и т.п.

    При успешном создании ресурса возвращается HTTP код 201, а также в заголовке `Location` передается адрес созданного ресурса.

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

    При успешном удалении возвращается 200 (OK) код HTTP, совместно с телом ответа, содержащим данные удаленного ресурса. Также возможно использование HTTP кода 204 (NO CONTENT) без тела ответа. Согласно спецификации HTTP, DELETE запрос идемпотентен. Если вы выполняете DELETE запрос к ресурсу, он удаляется. Повторный DELETE запрос к ресурсу закончится также: ресурс удален. Если DELETE запрос используется для декремента счетчика, DELETE запрос не является идемпотентным. Используйте POST для не идемпотентных операций.

    Тем не менее, существует предостережение об идемпотентности DELETE. Повторный DELETE запрос к ресурсу часто сопровождается 404 (NOT FOUND) кодом HTTP по причине того, что ресурс уже удален (например из базы данных) и более не доступен. Это делает DELETE операцию не идемпотентной, но это общепринятый компромисс на тот случай, если ресурс был удален из базы данных, а не помечен, как удаленный.

    Что такое такое rest api?

    Что такое такое rest api ? Объясните, пожалуйста, понятными словами. Википедия, увы, не смогла ответить.

    Специалист по rest api должен разбираться в, например, api vk ? Или это разные вообше вещи? В чем разница?

    • Вопрос задан более трёх лет назад
    • 105653 просмотра

    API социальных сетей — это вполне типичные примеры реализации REST API.

    REST (RESTful) — это общие принципы организации взаимодействия приложения/сайта с сервером посредством протокола HTTP. Особенность REST в том, что сервер не запоминает состояние пользователя между запросами — в каждом запросе передаётся информация, идентифицирующая пользователя (например, token, полученный через OAuth-авторизацию) и все параметры, необходимые для выполнения операции.

    Всё взаимодействие с сервером сводится к 4 операциям (4 — это необходимый и достаточный минимум, в конкретной реализации типов операций может быть больше):
    1. получение данных с сервера (обычно в формате JSON, или XML)
    2. добавление новых данных на сервер
    3. модификация существующих данных на сервере
    4. удаление данных на сервере

    Операция получения данных не может приводить к изменению состояния сервера.

    Для каждого типа операции используется свой метод HTTP-запроса:
    1. получение — GET
    2. добавление — POST
    3. модификация — PUT
    4. удаление — DELETE

    GET-запрос /rest/users — получение информации о всех пользователях
    GET-запрос /rest/users/125 — получение информации о пользователе с > POST-запрос /rest/users — добавление нового пользователя
    PUT-запрос /rest/users/125 — изменение информации о пользователе с > DELETE-запрос /rest/users/125 — удаление пользователя с >

    Разработка веб-API Web API design

    Большинство современных веб-приложений предоставляют API, которые клиенты могут использовать для взаимодействия с приложением. Most modern web applications expose APIs that clients can use to interact with the application. Качественно спроектированный API должен поддерживать следующее: A well-designed web API should aim to support:

    Независимость от платформы. Platform independence. Любой клиент должен иметь возможность вызывать API, независимо от того, как API реализован внутренне. Any client should be able to call the API, regardless of how the API is implemented internally. Для этого требуется использование стандартных протоколов, а также наличие механизма, при котором клиент и веб-службы могут согласовать формат данных для обмена. This requires using standard protocols, and having a mechanism whereby the client and the web service can agree on the format of the data to exchange.

    Развитие службы. Service evolution. Веб-API должен иметь возможность развиваться и расширять набор функций независимо от клиентских приложений. The web API should be able to evolve and add functionality independently from client applications. По мере развития API имеющиеся клиентские приложения должны продолжать работать без изменений. As the API evolves, existing client applications should continue to function without modification. Все функции должны быть доступными, чтобы клиентские приложения могли полноценно их использовать. All functionality should be discoverable so that client applications can fully use it.

    В этом руководстве описываются проблемы, которые следует учитывать при разработке веб-API. This guidance describes issues that you should consider when designing a web API.

    Общие сведения о REST Introduction to REST

    В 2000 году Рой Филдинг предложил архитектурный подход к разработке веб-служб — передачу репрезентативного состояния (REST). In 2000, Roy Fielding proposed Representational State Transfer (REST) as an architectural approach to designing web services. REST — это архитектурная концепция создания распределенных систем на основе гиперсред. REST is an architectural style for building distributed systems based on hypermedia. Модель REST не зависит от каких-либо базовых протоколов и не требует привязки к HTTP. REST is independent of any underlying protocol and is not necessarily tied to HTTP. Однако наиболее распространенные реализации REST используют HTTP в качестве протокола приложения. Поэтому это руководство посвящено разработке REST API для HTTP. However, most common REST implementations use HTTP as the application protocol, and this guide focuses on designing REST APIs for HTTP.

    Основное преимущество при использовании REST с протоколом HTTP заключается в применении открытых стандартов и отсутствии необходимости в определенной реализации API или клиентских приложений. A primary advantage of REST over HTTP is that it uses open standards, and does not bind the implementation of the API or the client applications to any specific implementation. Например, веб-службу REST можно написать в ASP.NET, а клиентские приложения могут использовать любой язык или набор инструментов, позволяющие создавать HTTP-запросы и анализировать HTTP-ответы. For example, a REST web service could be written in ASP.NET, and client applications can use any language or toolset that can generate HTTP requests and parse HTTP responses.

    Ниже приведены некоторые основные принципы проектирования интерфейсов RESTful API, использующих протокол HTTP: Here are some of the main design principles of RESTful APIs using HTTP:

    REST API разрабатываются на основе ресурса, который может быть любым типом объекта, данных или службы, к которому может получить доступ клиент. REST APIs are designed around resources, which are any kind of object, data, or service that can be accessed by the client.

    У ресурса есть идентификатор (универсальный код ресурса (URI)), который уникально идентифицирует этот ресурс. A resource has an identifier, which is a URI that uniquely identifies that resource. Например, URI для определенного клиентского заказа может быть таким: For example, the URI for a particular customer order might be:

    Клиенты взаимодействуют со службой путем обмена представлениями ресурсов. Clients interact with a service by exchanging representations of resources. Многие веб-API используют JSON в качества формата для обмена. Many web APIs use JSON as the exchange format. Например, в результате запроса GET к приведенному выше URI может вернуться такой текст ответа: For example, a GET request to the URI listed above might return this response body:

    Интерфейсы REST API используют единый интерфейс, который позволяет отделить реализации клиента и службы. REST APIs use a uniform interface, which helps to decouple the client and service implementations. Для REST API, созданных на основе протокола HTTP, единый интерфейс будет использовать стандартные HTTP-команды для выполнения операций с ресурсами. For REST APIs built on HTTP, the uniform interface includes using standard HTTP verbs to perform operations on resources. Наиболее часто выполняемые операции: GET, POST, PUT, PATCH и DELETE. The most common operations are GET, POST, PUT, PATCH, and DELETE.

    REST API использует модель запросов без отслеживания состояния. REST APIs use a stateless request model. HTTP-запросы должны быть независимыми и могут создаваться в любом порядке, поэтому сохранение сведений о переходном состоянии между запросами не представляется возможным. HTTP requests should be independent and may occur in any order, so keeping transient state information between requests is not feasible. Сведения хранятся только в самих ресурсах, и каждый запрос должен быть атомарной операцией. The only place where information is stored is in the resources themselves, and each request should be an atomic operation. Благодаря этому ограничению веб-службы имеют высокую масштабируемость, так как нет необходимости сохранять сходство между клиентами и конкретными серверами. This constraint enables web services to be highly scalable, because there is no need to retain any affinity between clients and specific servers. Каждый сервер может обрабатывать любой запрос от любого клиента. Any server can handle any request from any client. Тем не менее, другие факторы могут ограничить масштабируемость. That said, other factors can limit scalability. Например, многие веб-службы записывают данные в серверное хранилище данных, что может быть трудно масштабировать. Дополнительные сведения о стратегиях масштабирования хранилища данных см. в разделе горизонтальное, вертикальное и функциональное секционирование данных. For example, many web services write to a backend data store, which may be hard to scale out. For more information about strategies to scale out a data store, see Horizontal, vertical, and functional data partitioning.

    Интерфейсами REST API управляют ссылки на гиперсреды, которые содержатся в представлении. REST APIs are driven by hypermedia links that are contained in the representation. Например, ниже показано JSON-представление заказа. For example, the following shows a JSON representation of an order. Оно содержит ссылки для получения или обновления клиента, связанного с заказом. It contains links to get or update the customer associated with the order.

    В 2008 году Леонард Ричардсон предложил следующую модель зрелости для веб-API: In 2008, Leonard Richardson proposed the following maturity model for web APIs:

    • Уровень 0. Определение одного URI, и все операции будут POST-запросами к этому URI. Level 0: Define one URI, and all operations are POST requests to this URI.
    • Уровень 1. Создание отдельных URI для отдельных ресурсов. Level 1: Create separate URIs for individual resources.
    • Уровень 2. Использование методов HTTP для определения операций с ресурсами. Level 2: Use HTTP methods to define operations on resources.
    • Уровень 3. Использование гиперсред (HATEOAS, описан ниже). Level 3: Use hypermedia (HATEOAS, described below).

    Уровень 3 соответствует настоящему RESTful API, согласно определению Филдинга. Level 3 corresponds to a truly RESTful API according to Fielding’s definition. На практике многие опубликованные веб-API находятся где-то около уровня 2. In practice, many published web APIs fall somewhere around level 2.

    Упорядочивание API вокруг ресурсов Organize the API around resources

    Сосредоточьтесь на бизнес-сущностях, предоставляемых веб-API. Focus on the business entities that the web API exposes. Например, в системе электронной коммерции основными сущностями могут быть клиенты и заказы. For example, in an e-commerce system, the primary entities might be customers and orders. Создание заказа может осуществляться путем отправки HTTP-запроса POST, содержащего сведения о заказе. Creating an order can be achieved by sending an HTTP POST request that contains the order information. HTTP-ответ указывает на успешность размещения заказа. The HTTP response indicates whether the order was placed successfully or not. Когда это возможно, универсальные коды ресурсов должны основываться на существительных (ресурсе), а не на глаголах (операциях c ресурсом). When possible, resource URIs should be based on nouns (the resource) and not verbs (the operations on the resource).

    Ресурс не должен основываться на одном физическом элементе данных. A resource doesn’t have to be based on a single physical data item. Например, ресурс заказа может быть реализован внутри системы с использованием нескольких таблиц в реляционной базе данных, однако представлен в клиентском приложении как единая сущность. For example, an order resource might be implemented internally as several tables in a relational database, but presented to the client as a single entity. Избегайте создания API, которые просто отражают внутреннюю структуру базы данных. Avoid creating APIs that simply mirror the internal structure of a database. Цель REST — моделировать сущности и операции, которые приложение может выполнять в этих сущностях. The purpose of REST is to model entities and the operations that an application can perform on those entities. Внутренняя реализация должна быть скрыта от клиента. A client should not be exposed to the internal implementation.

    Сущности часто группируются в коллекции (заказов, клиентов). Entities are often grouped together into collections (orders, customers). Коллекция — это отдельный ресурс из элемента в коллекции и должен иметь свой собственный URI. A collection is a separate resource from the item within the collection, and should have its own URI. Например, следующий URI может представлять коллекцию заказов: For example, the following URI might represent the collection of orders:

    В результате отправки HTTP-запроса GET на URI коллекции возвращается список элементов в коллекции. Sending an HTTP GET request to the collection URI retrieves a list of items in the collection. Каждый элемент в коллекции также имеет свой собственный универсальный код ресурса (URI). Each item in the collection also has its own unique URI. HTTP-запрос GET к URI элемента возвращает подробные сведения об этом элементе. An HTTP GET request to the item’s URI returns the details of that item.

    Используйте единое соглашение об именовании в универсальных кодах ресурсов. Adopt a consistent naming convention in URIs. В целом это помогает использовать существительные во множественном числе для URI, ссылающихся на коллекции. In general, it helps to use plural nouns for URIs that reference collections. Рекомендуется упорядочивать универсальные коды ресурсов для коллекций и элементов в иерархии. It’s a good practice to organize URIs for collections and items into a hierarchy. Например, /customers — это путь к коллекции клиентов, а /customers/5 — путь к клиенту с идентификатором равным 5. For example, /customers is the path to the customers collection, and /customers/5 is the path to the customer with ID equal to 5. Этот подход позволяет обеспечивать простоту веб-API. This approach helps to keep the web API intuitive. Кроме того, множество платформ веб-API могут направлять запросы на основании параметризованных путей URI, поэтому можно определить маршрут для пути /customers/ . Also, many web API frameworks can route requests based on parameterized URI paths, so you could define a route for the path /customers/ .

    Также следует продумать связи между разными типами ресурсов и способы предоставления этих связей. Also consider the relationships between different types of resources and how you might expose these associations. Например, /customers/5/orders может представлять все заказы для клиента 5. For example, the /customers/5/orders might represent all of the orders for customer 5. Вы также можете пойти в другом направлении и представить связь между заказом и конкретным клиентом посредством универсального кода ресурса, например /orders/99/customer . You could also go in the other direction, and represent the association from an order back to a customer with a URI such as /orders/99/customer . Однако чрезмерное расширение этой модели может вызвать трудности. However, extending this model too far can become cumbersome to implement. Более рациональное решение — предоставить ссылки с возможностью перехода на связанные ресурсы в тексте HTTP-ответа. A better solution is to provide navigable links to associated resources in the body of the HTTP response message. Этот механизм более подробно описан в разделе Использование HATEOAS для включения навигации к связанным ресурсам. This mechanism is described in more detail in the section Use HATEOAS to enable navigation to related resources.

    В более сложных системах очевидным решением может показаться предоставление URI, позволяющих клиенту переходить между несколькими уровнями связей, например /customers/1/orders/99/products . In more complex systems, it can be tempting to provide URIs that enable a client to navigate through several levels of relationships, such as /customers/1/orders/99/products . Однако такой уровень сложности трудно обслуживать и адаптировать в случае дальнейшего изменения связей между ресурсами. However, this level of complexity can be difficult to maintain and is inflexible if the relationships between resources change in the future. Вместо этого постарайтесь сделать URI максимально простыми. Instead, try to keep URIs relatively simple. Как только у приложения появляется ссылка на ресурс, оно может использовать эту ссылку для поиска элементов, связанных с указанным ресурсом. Once an application has a reference to a resource, it should be possible to use this reference to find items related to that resource. Предыдущий запрос можно заменить на URI /customers/1/orders , чтобы найти все заказы для клиента 1, а затем — на /orders/99/products , чтобы найти продукты в этом заказе. The preceding query can be replaced with the URI /customers/1/orders to find all the orders for customer 1, and then /orders/99/products to find the products in this order.

    Старайтесь использовать универсальные коды ресурсов не сложнее collection/item/collection. Avoid requiring resource URIs more complex than collection/item/collection.

    Кроме того, следует учесть, что все веб-запросы увеличивают нагрузку на веб-сервер, Another factor is that all web requests impose a load on the web server. которая растет вместе с числом запросов. The more requests, the bigger the load. Поэтому старайтесь избегать создания веб-API с множественными операциями ввода-вывода, которые предоставляют большое количество небольших ресурсов. Therefore, try to avoid «chatty» web APIs that expose a large number of small resources. Такой API может потребовать от клиентского приложения отправки нескольких запросов для поиска всех необходимых данных. Such an API may require a client application to send multiple requests to find all of the data that it requires. Вместо этого можно выполнить денормализацию данных и объединить соответствующую информацию в более крупные ресурсы, которые можно получить с помощью одного запроса. Instead, you might want to denormalize the data and combine related information into bigger resources that can be retrieved with a single request. Однако следует сохранять равновесие в этом подходе, чтобы избежать получения чрезмерного объема данных, которые не нужны клиенту. However, you need to balance this approach against the overhead of fetching data that the client doesn’t need. Получение больших объектов может увеличить задержку запроса и привести к дополнительным расходам на пропускную способность. Retrieving large objects can increase the latency of a request and incur additional bandwidth costs. Дополнительные сведения об этих антишаблонах производительности см. в статье Антишаблон отправки множественных операций ввода-вывода и Антишаблон лишней выборки. For more information about these performance antipatterns, see Chatty I/O and Extraneous Fetching.

    Избегайте зависимостей между веб-API и базовыми источниками данных. Avoid introducing dependencies between the web API and the underlying data sources. Например, если данные хранятся в реляционной базе данных, веб-API не требуется предоставлять каждую таблицу в виде коллекции ресурсов. For example, if your data is stored in a relational database, the web API doesn’t need to expose each table as a collection of resources. Это, вероятно, будет неэффективная архитектура. In fact, that’s probably a poor design. Вместо этого представьте веб-API в виде абстракции базы данных. Instead, think of the web API as an abstraction of the database. При необходимости создайте уровень сопоставления между базой данных и веб-API. If necessary, introduce a mapping layer between the database and the web API. Таким образом клиентские приложения изолированы от изменений в базовой схеме базы данных. That way, client applications are isolated from changes to the underlying database scheme.

    Наконец, сопоставление каждой операции, реализованной веб-API, с конкретным источником не всегда возможно. Finally, it might not be possible to map every operation implemented by a web API to a specific resource. Такие безресурсные сценарии можно обрабатывать с помощью HTTP-запросов, вызывающих определенную функцию и возвращающих результаты в виде ответного HTTP-сообщения. You can handle such non-resource scenarios through HTTP requests that invoke a function and return the results as an HTTP response message. Например, веб-API, реализующий простые расчетные операции, такие как добавление и вычитание, может предоставить универсальные коды ресурсов (URI), представляющие эти операции в виде псевдоресурсов, и использовать строку запроса для указания требуемых параметров. For example, a web API that implements simple calculator operations such as add and subtract could provide URIs that expose these operations as pseudo resources and use the query string to specify the parameters required. Например, запрос GET к URI /Add? операнд1 = 99 & операнд2 = 1 возвратит ответное сообщение с текстом, содержащим значение 100. For example, a GET request to the URI /add?operand1=99&operand2=1 would return a response message with the body containing the value 100. Однако следует использовать эти формы универсальных кодов ресурсов (URI) с осторожностью. However, only use these forms of URIs sparingly.

    Определение операций с точки зрения методов HTTP Define operations in terms of HTTP methods

    Протокол HTTP определяет несколько методов, назначающих запросу семантическое значение. The HTTP protocol defines a number of methods that assign semantic meaning to a request. Ниже приведены наиболее распространенные методы HTTP, используемые большинством веб-API RESTful: The common HTTP methods used by most RESTful web APIs are:

    • GET. Возвращает представление ресурса по указанному универсальному коду ресурса (URI). GET retrieves a representation of the resource at the specified URI. Текст ответного сообщения содержит сведения о запрашиваемом ресурсе. The body of the response message contains the details of the requested resource.
    • POST. Создает новый ресурс по указанному URI. POST creates a new resource at the specified URI. Текст запроса содержит сведения о новом ресурсе. The body of the request message provides the details of the new resource. Обратите внимание, что метод POST также можно использовать для запуска операций, не относящихся непосредственно к созданию ресурсов. Note that POST can also be used to trigger operations that don’t actually create resources.
    • PUT. Создает или заменяет ресурсы по указанному URI. PUT either creates or replaces the resource at the specified URI. В тексте сообщения запроса указан создаваемый или обновляемый ресурс. The body of the request message specifies the resource to be created or updated.
    • PATCH. Выполняет частичное обновление ресурса. PATCH performs a partial update of a resource. Текст запроса определяет набор изменений, применяемых к ресурсу. The request body specifies the set of changes to apply to the resource.
    • DELETE. Удаляет ресурс по указанному URI. DELETE removes the resource at the specified URI.

    Результат конкретного запроса должен зависеть от того, является ли целевой ресурс коллекцией или отдельным элементом. The effect of a specific request should depend on whether the resource is a collection or an individual item. В следующей таблице приведены общие соглашения, принятые большинством реализаций RESTFUL с помощью примера электронной коммерции. The following table summarizes the common conventions adopted by most RESTful implementations using the e-commerce example. Не все эти запросы могут быть реализованы—он зависит от конкретного сценария. Not all of these requests might be implemented—it depends on the specific scenario.

    Ресурс Resource POST POST GET GET PUT PUT DELETE DELETE
    /customers /customers Создание нового клиента Create a new customer Получение всех клиентов Retrieve all customers Массовое обновление клиентов Bulk update of customers Удаление всех клиентов Remove all customers
    /customers/1 /customers/1 Ошибка Error Получение сведений для клиента 1 Retrieve the details for customer 1 Обновление сведения о клиенте 1, если он существует Update the details of customer 1 if it exists Удаление клиента 1 Remove customer 1
    /customers/1/orders /customers/1/orders Создание нового заказа для клиента 1 Create a new order for customer 1 Получение всех заказов для клиента 1 Retrieve all orders for customer 1 Массовое обновление заказов для клиента 1 Bulk update of orders for customer 1 Удаление всех заказов для клиента 1 Remove all orders for customer 1

    Различия между POST, PUT и PATCH могут запутать новичков. The differences between POST, PUT, and PATCH can be confusing.

    Запрос POST создает ресурс. A POST request creates a resource. Сервер назначает URI для нового ресурса и возвращает этот URI клиенту. The server assigns a URI for the new resource, and returns that URI to the client. В модели REST запросы POST постоянно применяются к коллекциям. In the REST model, you frequently apply POST requests to collections. При этом новый ресурс добавляется в коллекцию. The new resource is added to the collection. Запрос POST также может использоваться для отправки данных для обработки в имеющийся ресурс без создания нового ресурса. A POST request can also be used to submit data for processing to an existing resource, without any new resource being created.

    Запрос PUT создает ресурс или обновляет имеющийся ресурс. A PUT request creates a resource or updates an existing resource. Клиент указывает универсальный код ресурса. The client specifies the URI for the resource. Текст запроса содержит полное представление ресурса. The request body contains a complete representation of the resource. Если ресурс с таким URI уже существует, он заменяется. If a resource with this URI already exists, it is replaced. В противном случае создается новый ресурс, если сервер поддерживает это. Otherwise a new resource is created, if the server supports doing so. Запросы PUT чаще всего применяются к ресурсам, которые являются отдельными элементами, например конкретные клиенты, а не к коллекциям. PUT requests are most frequently applied to resources that are individual items, such as a specific customer, rather than collections. Сервер может поддерживать обновления, но не создание через PUT. A server might support updates but not creation via PUT. Требуется ли поддерживать создание через PUT зависит от того, может ли клиент назначать информативный URI ресурсу до его существования. Whether to support creation via PUT depends on whether the client can meaningfully assign a URI to a resource before it exists. Если нет, используйте POST для создания ресурсов, а PUT или PATCH для обновления. If not, then use POST to create resources and PUT or PATCH to update.

    Запрос PATCH выполняет частичное обновление имеющегося ресурса. A PATCH request performs a partial update to an existing resource. Клиент указывает универсальный код ресурса. The client specifies the URI for the resource. Текст запроса определяет набор изменений, применяемых к ресурсу. The request body specifies a set of changes to apply to the resource. Это может быть более эффективно, чем использование PUT, так как клиент отправляет только изменения, а не все представление ресурса. This can be more efficient than using PUT, because the client only sends the changes, not the entire representation of the resource. С технической точки зрения PATCH также может создать новый ресурс (указав набор обновлений для ресурса «null»), если это поддерживается сервером. Technically PATCH can also create a new resource (by specifying a set of updates to a «null» resource), if the server supports this.

    Запросы PUT должны быть идемпотентными. PUT requests must be idempotent. Если клиент отправляет тот же запрос PUT несколько раз, результаты всегда должны быть одинаковыми (тот же ресурс будет изменяться с теми же значениями). If a client submits the same PUT request multiple times, the results should always be the same (the same resource will be modified with the same values). Запросы POST и PATCH не будут гарантированно идемпотентными. POST and PATCH requests are not guaranteed to be idempotent.

    Соответствие семантике HTTP Conform to HTTP semantics

    В этом разделе описываются некоторые распространенные вопросы по проектированию API, соответствующего спецификации HTTP. This section describes some typical considerations for designing an API that conforms to the HTTP specification. Однако он не охватывает все возможные детали или сценарии. However, it doesn’t cover every possible detail or scenario. Если вы сомневаетесь, обратитесь к спецификациям HTTP. When in doubt, consult the HTTP specifications.

    Типы мультимедиа Media types

    Как упоминалось ранее, клиенты и серверы обмениваются представлениями ресурсов. As mentioned earlier, clients and servers exchange representations of resources. Например, в тексте запроса POST содержится представление создаваемого ресурса. For example, in a POST request, the request body contains a representation of the resource to create. В тексте запроса GET содержится представление получаемого ресурса. In a GET request, the response body contains a representation of the fetched resource.

    В протоколе HTTP форматы задаются с помощью типов мультимедиа, также называемых типами MIME. In the HTTP protocol, formats are specified through the use of media types, also called MIME types. Для недвоичных данных большинство веб-API поддерживают формат JSON (тип мультимедиа — application/json) и возможно XML (тип мультимедиа — application/xml). For non-binary data, most web APIs support JSON (media type = application/json) and possibly XML (media type = application/xml).

    Заголовок Content-Type в запросе или ответе определяет формат представления. The Content-Type header in a request or response specifies the format of the representation. Ниже приведен пример запроса POST, который включает в себя данные JSON: Here is an example of a POST request that includes JSON data:

    Если сервер не поддерживает данный тип мультимедиа, он возвращает код состояния HTTP 415 (неподдерживаемый тип носителя). If the server doesn’t support the media type, it should return HTTP status code 415 (Unsupported Media Type).

    Запрос клиента может включать заголовок Accept, содержащий список типов мультимедиа, которые клиент будет принимать от сервера в ответном сообщении. A client request can include an Accept header that contains a list of media types the client will accept from the server in the response message. Пример. For example:

    Если сервер не может соответствовать ни одному из указанных типов мультимедиа, он должен вернуть код состояния HTTP 406 (неприемлемо). If the server cannot match any of the media type(s) listed, it should return HTTP status code 406 (Not Acceptable).

    Методы GET GET methods

    Успешное выполнение метода GET обычно возвращает код состояния HTTP 200 (ОК). A successful GET method typically returns HTTP status code 200 (OK). Если ресурс не найден, метод должен вернуть код 404 (не найдено). If the resource cannot be found, the method should return 404 (Not Found).

    Методы POST POST methods

    Если метод POST создает новый ресурс, он возвращает код состояния HTTP 201 (создано). If a POST method creates a new resource, it returns HTTP status code 201 (Created). URI нового ресурса содержится в заголовке Location ответа. The URI of the new resource is included in the Location header of the response. Текст ответа содержит представление ресурса. The response body contains a representation of the resource.

    Если метод выполняет определенную обработку, но не создает новый ресурс, он может вернуть код состояния HTTP 200 и содержать результат операции в тексте ответа. If the method does some processing but does not create a new resource, the method can return HTTP status code 200 and include the result of the operation in the response body. Кроме того, при отсутствии результатов для возврата метод может вернуть код состояния HTTP 204 (нет содержимого) без текста ответа. Alternatively, if there is no result to return, the method can return HTTP status code 204 (No Content) with no response body.

    Если клиент помещает недопустимые данные в запрос, сервер должен вернуть код состояния HTTP 400 (неверный запрос). If the client puts invalid data into the request, the server should return HTTP status code 400 (Bad Request). Текст ответа может содержать дополнительные сведения об ошибке или ссылку на универсальный код ресурса (URI), по которому можно получить более подробную информацию. The response body can contain additional information about the error or a link to a URI that provides more details.

    Методы PUT PUT methods

    Если метод PUT создает новый ресурс, он возвращает код состояния HTTP 201 (создано), как и метод POST. If a PUT method creates a new resource, it returns HTTP status code 201 (Created), as with a POST method. Если метод обновляет имеющийся ресурс, он возвращает коды состояния 200 (ОК) или 204 (нет содержимого). If the method updates an existing resource, it returns either 200 (OK) or 204 (No Content). В некоторых случаях обновить имеющийся ресурс невозможно. In some cases, it might not be possible to update an existing resource. В этом случае рассмотрите возможность возврата кода состояния HTTP 409 (конфликт). In that case, consider returning HTTP status code 409 (Conflict).

    Рассмотрите возможность реализации массовых HTTP-операций PUT, поддерживающих пакетные обновления нескольких ресурсов в коллекции. Consider implementing bulk HTTP PUT operations that can batch updates to multiple resources in a collection. В запросе PUT должен быть указан универсальный код ресурса (URI) коллекции, а текст запроса должен содержать сведения о ресурсах, которые требуется изменить. The PUT request should specify the URI of the collection, and the request body should specify the details of the resources to be modified. Такой подход помогает сократить избыточность и повысить производительность. This approach can help to reduce chattiness and improve performance.

    Методы PATCH PATCH methods

    С помощью запроса PATCH клиент отправляет набор обновлений в имеющийся ресурс в виде документа с исправлениями. With a PATCH request, the client sends a set of updates to an existing resource, in the form of a patch document. Сервер обрабатывает документ с исправлениями, чтобы выполнить обновление. The server processes the patch document to perform the update. Документ с исправлениями не описывает весь ресурс, а только набор применяемых изменений. The patch document doesn’t describe the whole resource, only a set of changes to apply. Спецификация метода PATCH (RFC 5789) не определяет конкретный формат документов с исправлениями. The specification for the PATCH method (RFC 5789) doesn’t define a particular format for patch documents. Формат необходимо определить на основе типа мультимедиа в запросе. The format must be inferred from the media type in the request.

    Вероятно, наиболее распространенный формат данных для веб-API — JSON. JSON is probably the most common data format for web APIs. Есть два основных формата исправлений на основе JSON, называемые исправлением JSON и исправлением со слиянием JSON. There are two main JSON-based patch formats, called JSON patch and JSON merge patch.

    Исправление со слиянием JSON несколько проще. JSON merge patch is somewhat simpler. Документ с исправлениями имеет ту же структуру, что и исходный ресурс JSON, однако включает только подмножество полей, которые необходимо изменить или добавить. The patch document has the same structure as the original JSON resource, but includes just the subset of fields that should be changed or added. Кроме того, поле можно удалить, указав null для значения поля в документе с исправлениями. In addition, a field can be deleted by specifying null for the field value in the patch document. (Это означает, что исправление со слиянием не подходит, если исходный ресурс может иметь явные значения null.) (That means merge patch is not suitable if the original resource can have explicit null values.)

    Предположим, что исходный ресурс имеет следующее представление JSON: For example, suppose the original resource has the following JSON representation:

    Вот возможное исправление со слиянием JSON для этого ресурса: Here is a possible JSON merge patch for this resource:

    Это означает, что сервер обновляет price , удаляет color и добавляет size , а name и category не изменяются. This tells the server to update price , delete color , and add size , while name and category are not modified. Точные сведения об исправлении со слиянием JSON см. в документе RFC 7396. For the exact details of JSON merge patch, see RFC 7396. Тип носителя для исправления со слиянием JSON — application/merge-patch+json . The media type for JSON merge patch is application/merge-patch+json .

    Исправление со слиянием не подходит, если исходный ресурс может содержать явные значения null, из-за смысла значения null в документе с исправлениями. Merge patch is not suitable if the original resource can contain explicit null values, due to the special meaning of null in the patch document. Кроме того, в документе с исправлениями не указывается порядок, в котором сервер должен применять обновления. Also, the patch document doesn’t specify the order that the server should apply the updates. Это может иметь значение, в зависимости от данных и предметной области. That may or may not matter, depending on the data and the domain. Исправление JSON, определенное в RFC 6902, — более гибкое. JSON patch, defined in RFC 6902, is more flexible. Оно определяет изменения как последовательность выполняемых операций, It specifies the changes as a sequence of operations to apply. в частности добавление, удаление, замена, копирование и тестирование (для проверки значений). Operations include add, remove, replace, copy, and test (to validate values). Тип носителя для исправления JSON — application/json-patch+json . The media type for JSON patch is application/json-patch+json .

    Ниже приведены некоторые типичные ошибки, которые могут возникнуть при обработке запроса PATCH, вместе с соответствующим кодом состояния HTTP. Here are some typical error conditions that might be encountered when processing a PATCH request, along with the appropriate HTTP status code.

    Условие ошибки Error condition HTTP status code (Код состояния HTTP) HTTP status code
    Формат документа с исправлениями не поддерживается. The patch document format isn’t supported. 415 (неподдерживаемый тип носителя) 415 (Unsupported Media Type)
    Неправильный формат документа с исправлениями. Malformed patch document. 400 (недопустимый запрос) 400 (Bad Request)
    Документ с исправлениями действителен, но изменения нельзя применить к ресурсу в его текущем состоянии. The patch document is valid, but the changes can’t be applied to the resource in its current state. 409 (конфликт) 409 (Conflict)

    Методы DELETE DELETE methods

    Если операция удаления прошла успешно, веб-сервер должен вернуть ответ с кодом состояния HTTP 204, указывающим на успешное завершение процесса и отсутствие дополнительных сведений в тексте ответа. If the delete operation is successful, the web server should respond with HTTP status code 204, indicating that the process has been successfully handled, but that the response body contains no further information. Если ресурс не существует, веб-сервер может вернуть код HTTP 404 (не найдено). If the resource doesn’t exist, the web server can return HTTP 404 (Not Found).

    Асинхронные операции Asynchronous operations

    Иногда для завершения операции POST, помещения, исправления или удаления может потребоваться обработка, которая занимает некоторое время. Sometimes a POST, PUT, PATCH, or DELETE operation might require processing that takes a while to complete. Если дожидаться завершения до отправки ответа клиенту, это может привести к неприемлемой задержке. If you wait for completion before sending a response to the client, it may cause unacceptable latency. В этом случае рассмотрите возможность создания асинхронной операции. If so, consider making the operation asynchronous. Верните код состояния HTTP 202, указывающий, что запрос был принят в обработку, но не завершен. Return HTTP status code 202 (Accepted) to indicate the request was accepted for processing but is not completed.

    Следует предоставить конечную точку, которая возвращает состояние асинхронного запроса, чтобы клиент мог отслеживать состояние, опрашивая конечную точку состояния. You should expose an endpoint that returns the status of an asynchronous request, so the client can monitor the status by polling the status endpoint. Включите URI конечной точки состояния в заголовок Location ответа 202. Include the URI of the status endpoint in the Location header of the 202 response. Пример. For example:

    Если клиент отправляет запрос GET к этой конечной точке, ответ должен содержать текущее состояние запроса. If the client sends a GET request to this endpoint, the response should contain the current status of the request. Кроме того, он также может включать предполагаемое время выполнения или ссылку для отмены операции. Optionally, it could also include an estimated time to completion or a link to cancel the operation.

    Если асинхронная операция создает новый ресурс, конечная точка состояния должна вернуть код состояния 303 (см. другие) после завершения операции. If the asynchronous operation creates a new resource, the status endpoint should return status code 303 (See Other) after the operation completes. В ответе 303 включите заголовок Location, который предоставляет URI нового ресурса: In the 303 response, include a Location header that gives the URI of the new resource:

    Фильтрация и разбитие данных на страницы Filter and paginate data

    Предоставление коллекции ресурсов через один универсальный код ресурса (URI) может привести к тому, что приложения будут получать крупные объемы данных, когда нужно лишь подмножество информации. Exposing a collection of resources through a single URI can lead to applications fetching large amounts of data when only a subset of the information is required. Предположим, клиентскому приложению необходимо найти все заказы с суммой выше заданного значения. For example, suppose a client application needs to find all orders with a cost over a specific value. Он может получить все заказы через универсальный код ресурса (URI) /orders, а затем отфильтровать эти заказы на стороне клиента. It might retrieve all orders from the /orders URI and then filter these orders on the client side. Очевидно, что этот процесс крайне неэффективен. Clearly this process is highly inefficient. Он впустую использует пропускную способность сети и вычислительные ресурсы сервера, на котором размещен веб-API. It wastes network bandwidth and processing power on the server hosting the web API.

    Вместо этого API может разрешить передачу фильтра в строке запроса URI, например /orders?minCost=n. Instead, the API can allow passing a filter in the query string of the URI, such as /orders?minCost=n. Веб-API отвечает за синтаксический анализ и обработку параметра minCost в строке запроса и возврат отфильтрованных результатов на стороне сервера. The web API is then responsible for parsing and handling the minCost parameter in the query string and returning the filtered results on the server side.

    Запросы GET по ресурсам коллекций потенциально могут возвращать большое число элементов. GET requests over collection resources can potentially return a large number of items. При проектировании веб-API следует ввести ограничение на объем данных, возвращаемый одним запросом. You should design a web API to limit the amount of data returned by any single request. Рассмотрите возможность использования строк запроса, определяющих максимальное количество элементов для получения и начальное смещение в коллекции. Consider supporting query strings that specify the maximum number of items to retrieve and a starting offset into the collection. Пример. For example:

    Также рассмотрите возможность наложения верхнего предела на количество возвращаемых элементов, чтобы предотвратить атаки типа «отказ в обслуживании». Also consider imposing an upper limit on the number of items returned, to help prevent Denial of Service attacks. Для поддержки клиентских приложений запросы GET, возвращающие разбитые по страницам данные, должны также включать какие-либо метаданные, указывающие общее число ресурсов, доступных в коллекции. To assist client applications, GET requests that return paginated data should also include some form of metadata that indicate the total number of resources available in the collection.

    Аналогичную стратегию для сортировки данных можно также применить при их получении. Вы можете указать параметр сортировки, использующий имя поля в качестве значения, например /orders?sort=ProductID. You can use a similar strategy to sort data as it is fetched, by prov > Однако такой подход может негативно отразиться на кэшировании (так как параметры строки запроса составляют часть идентификатора ресурса, используемого многими реализациями кэша в качестве ключа к кэшированным данным). However, this approach can have a negative effect on caching, because query string parameters form part of the resource identifier used by many cache implementations as the key to cached data.

    Вы можете расширить этот подход и ограничить возвращаемые поля для каждого элемента, если каждый элемент содержит большой объем данных. You can extend this approach to limit the fields returned for each item, if each item contains a large amount of data. Например, используйте параметр строки запроса, принимающий разделенный запятыми список полей, например /orders?fields=ProductID,Quantity. For example, you could use a query string parameter that accepts a comma-delimited list of fields, such as /orders?fields=ProductID,Quantity.

    Присвойте содержательные значения по умолчанию всем необязательным параметрам в строках запроса. Give all optional parameters in query strings meaningful defaults. Например, установите параметру limit значение 10, а параметру offset — 0, если вы реализуете разбиение по страницам, параметру сортировки в качестве значения задайте ключ ресурса, если вы реализуете упорядочение, а в параметре fields укажите все поля в ресурсе при поддержке проекций. For example, set the limit parameter to 10 and the offset parameter to 0 if you implement pagination, set the sort parameter to the key of the resource if you implement ordering, and set the fields parameter to all fields in the resource if you support projections.

    Поддержка частичных ответов для больших двоичных ресурсов Support partial responses for large binary resources

    Ресурс может содержать большие двоичные поля, такие как файлы или изображения. A resource may contain large binary fields, such as files or images. Чтобы преодолеть проблемы, вызванные ненадежными и прерывистыми соединениями, а также улучшить время отклика, можно реализовать получение таких ресурсов пофрагментно. To overcome problems caused by unreliable and intermittent connections and to improve response times, consider enabling such resources to be retrieved in chunks. Для этого веб-API должен поддерживать заголовок Accept-Ranges для запросов GET по большим ресурсам. To do this, the web API should support the Accept-Ranges header for GET requests for large resources. Этот заголовок указывает, что операция GET поддерживает частичные запросы. This header indicates that the GET operation supports partial requests. Клиентское приложение может отправлять запросы GET, которые возвращают подмножество ресурса, указанное в виде диапазона байтов. The client application can submit GET requests that return a subset of a resource, specified as a range of bytes.

    Кроме того, рассмотрите возможность применения HTTP-запросов HEAD для этих ресурсов. Also, consider implementing HTTP HEAD requests for these resources. Запрос HEAD аналогичен запросу GET с тем исключением, что он возвращает только заголовок HTTP, описывающий ресурс, и пустое сообщение. A HEAD request is similar to a GET request, except that it only returns the HTTP headers that describe the resource, with an empty message body. Клиентское приложение может отправить запрос HEAD, чтобы определить необходимость получения ресурса с помощью частичных запросов GET. A client application can issue a HEAD request to determine whether to fetch a resource by using partial GET requests. Пример. For example:

    Вот пример сообщения ответа: Here is an example response message:

    Заголовок Content-Length содержит общий размер ресурса, а заголовок Accept-Ranges указывает, что соответствующая операция GET поддерживает частичные результаты. The Content-Length header gives the total size of the resource, and the Accept-Ranges header indicates that the corresponding GET operation supports partial results. Клиентское приложение может использовать эту информацию для получения изображения небольшими фрагментами. The client application can use this information to retrieve the image in smaller chunks. Первый запрос возвращает первые 2500 байт с помощью заголовка «Range»: The first request fetches the first 2500 bytes by using the Range header:

    Ответное сообщение указывает, что это частичный ответ, возвращая код состояния HTTP 206. The response message indicates that this is a partial response by returning HTTP status code 206. Заголовок «Content-Length» указывает фактическое число возвращаемых байтов в тексте сообщения (не размер ресурса), а заголовок «Content-Range» указывает, какая это часть ресурса (байты 0–2499 из 4580): The Content-Length header specifies the actual number of bytes returned in the message body (not the size of the resource), and the Content-Range header indicates which part of the resource this is (bytes 0-2499 out of 4580):

    Последующий запрос от клиентского приложения может получить оставшуюся часть ресурса. A subsequent request from the client application can retrieve the remainder of the resource.

    Использование подхода HATEOAS для обеспечения возможности перехода к связанным ресурсам Use HATEOAS to enable navigation to related resources

    Одна из основных целей реализации модели REST — получение возможности перемещаться внутри всего набора ресурсов без предварительного знания схемы универсальных кодов ресурсов (URI). One of the primary motivations behind REST is that it should be possible to navigate the entire set of resources without requiring prior knowledge of the URI scheme. Каждый HTTP-запрос GET должен возвращать сведения, необходимые для поиска ресурсов, напрямую связанных с запрашиваемым объектом, посредством гиперссылок, включенных в ответ. Запросу GET также необходимо предоставить сведения, описывающие операции, доступные в каждом из этих ресурсов. Each HTTP GET request should return the information necessary to find the resources related directly to the requested object through hyperlinks included in the response, and it should also be provided with information that describes the operations available on each of these resources. Этот принцип называется HATEOAS (гипертекст как обработчик состояния приложения). This principle is known as HATEOAS, or Hypertext as the Engine of Application State. Система фактически представляет собой конечный автомат. Ответ по каждому запросу содержит сведения, необходимые для перемещения между состояниями. Другие сведения не требуются. The system is effectively a finite state machine, and the response to each request contains the information necessary to move from one state to another; no other information should be necessary.

    На сегодняшний день не существует стандартов или спецификаций, определяющих правила моделирования принципа HATEOAS. Currently there are no standards or specifications that define how to model the HATEOAS principle. Примеры в этом разделе демонстрируют одно из возможных решений. The examples shown in this section illustrate one possible solution.

    Например, чтобы обрабатывать связь между заказом и клиентом, представление заказа может включать ссылки, которые идентифицируют доступные операции для отправителя заказа. For example, to handle the relationship between an order and a customer, the representation of an order could include links that identify the available operations for the customer of the order. Вот возможное представление: Here is a possible representation:

    В этом примере в массиве links есть набор ссылок. In this example, the links array has a set of links. Каждая ссылка представляет операцию в связанной сущности. Each link represents an operation on a related entity. Данные для каждой ссылки включают связь («customer»), URI ( https://adventure-works.com/customers/3 ), метод HTTP и поддерживаемые типы MIME. The data for each link includes the relationship («customer»), the URI ( https://adventure-works.com/customers/3 ), the HTTP method, and the supported MIME types. Это все данные, необходимые клиентскому приложению, чтобы иметь возможность вызова операции. This is all the information that a client application needs to be able to invoke the operation.

    Массив links также включает автореферентные сведения, относящиеся к полученному ресурсу. The links array also includes self-referencing information about the resource itself that has been retrieved. Они имеют отношение self. These have the relationship self.

    Набор возвращаемых ссылок может изменяться в зависимости от состояния ресурса. The set of links that are returned may change, depending on the state of the resource. Вот почему гипертекст является «обработчиком состояния приложения». This is what is meant by hypertext being the «engine of application state.»

    Управление версиями веб-API RESTful Versioning a RESTful web API

    Маловероятно, что веб-API останется статичным. It is highly unlikely that a web API will remain static. По мере изменения бизнес-требований добавляются новые коллекции ресурсов, изменяются связи между ресурсами и структура данных в ресурсах. As business requirements change new collections of resources may be added, the relationships between resources might change, and the structure of the data in resources might be amended. Несмотря на то что обновление веб-API для соответствия новым или измененным требованиям — довольно простой процесс, вам необходимо учесть, какое воздействие эти изменения окажут на клиентские приложения, использующие веб-API. While updating a web API to handle new or differing requirements is a relatively straightforward process, you must consider the effects that such changes will have on client applications consuming the web API. Причина в том, что хотя разработка и реализация веб-API имеет полный контроль над этим API, разработчик не имеет такой же уровень контроля над клиентскими приложениями, который может быть создан сторонними организациями, работающими удаленно. The issue is that although the developer designing and implementing a web API has full control over that API, the developer does not have the same degree of control over client applications, which may be built by third-party organizations operating remotely. В первую очередь необходимо позволить существующим клиентским приложениям продолжать работу без изменений, при этом предоставляя новым клиентским приложениям доступ к новым функциям и ресурсам. The primary imperative is to enable existing client applications to continue functioning unchanged while allowing new client applications to take advantage of new features and resources.

    Управление версиями позволяет веб-API указывать предоставляемые функции и ресурсы, за счет чего клиентское приложение может отправлять запросы для определенной версии функции или ресурса. Versioning enables a web API to indicate the features and resources that it exposes, and a client application can submit requests that are directed to a specific version of a feature or resource. В следующих разделах описано несколько различных подходов со своими преимуществами и недостатками. The following sections describe several different approaches, each of which has its own benefits and trade-offs.

    Отсутствие управления версиями No versioning

    Эта простейший подход, приемлемый для некоторых внутренних API. This is the simplest approach, and may be acceptable for some internal APIs. Значительные изменения можно представить в виде новых ресурсов или новых ссылок. Significant changes could be represented as new resources or new links. Добавление содержимого в существующие ресурсы может не представлять критические изменения, так как клиентские приложения, не ожидающие просмотра этого содержимого, будут игнорировать его. Adding content to existing resources might not present a breaking change as client applications that are not expecting to see this content will ignore it.

    Например, запрос на универсальный код ресурса (URI) https://adventure-works.com/customers/3 должен вернуть сведения одного клиента с полями id , name и address , которые ожидает клиентское приложение. For example, a request to the URI https://adventure-works.com/customers/3 should return the details of a single customer containing id , name , and address fields expected by the client application:

    Для простоты примеры ответов в этом разделе не содержат ссылок HATEOAS. For simplicity, the example responses shown in this section do not include HATEOAS links.

    Если поле DateCreated добавить в схему ресурса клиента, ответ будет выглядеть следующим образом: If the DateCreated field is added to the schema of the customer resource, then the response would look like this:

    Существующие клиентские приложения могут продолжить работать без ошибок, если они могут пропускать нераспознанные поля, в то время как при проектировании новых клиентских приложений можно обеспечить поддержку новых полей. Existing client applications might continue functioning correctly if they are capable of ignoring unrecognized fields, while new client applications can be designed to handle this new field. Однако внесение более серьезных изменений в схему ресурсов (таких как удаление или переименование полей) или изменение связей между ресурсами могут быть значительными изменениями, мешающими корректной работе существующих клиентских приложений. However, if more radical changes to the schema of resources occur (such as removing or renaming fields) or the relationships between resources change then these may constitute breaking changes that prevent existing client applications from functioning correctly. В таких ситуациях следует рассмотреть один из следующих подходов. In these situations, you should consider one of the following approaches.

    Управление версиями через универсальные коды ресурсов (URI) URI versioning

    При каждом изменении веб-API или схемы ресурсов вы добавляете номер версии в универсальный код (URI) каждого ресурса. Each time you modify the web API or change the schema of resources, you add a version number to the URI for each resource. Уже существующие универсальные коды ресурсов (URI) должны продолжить функционировать без изменений, возвращая ресурсы, соответствующие их исходной схеме. The previously existing URIs should continue to operate as before, returning resources that conform to their original schema.

    Расширение предыдущего примера, если поле address переструктурировано в подполя, содержащие каждую составляющую часть адреса (например, streetAddress , city , state и zipCode ), эта версия ресурса может быть предоставлена с помощью URI, содержащего номер версии, например https://adventure-works.com/v2/customers/3 : Extending the previous example, if the address field is restructured into subfields containing each constituent part of the address (such as streetAddress , city , state , and zipCode ), this version of the resource could be exposed through a URI containing a version number, such as https://adventure-works.com/v2/customers/3 :

    Этот механизм управления версиями очень прост, но для него требуется, чтобы сервер направлял запрос к соответствующей конечной точке. This versioning mechanism is very simple but depends on the server routing the request to the appropriate endpoint. Однако этот подход может стать чрезмерно сложным по мере прохождения веб-API через несколько итераций и необходимости поддержки сервером нескольких различных версий. However, it can become unwieldy as the web API matures through several iterations and the server has to support a number of different versions. Кроме того, c пуристической точки зрения, во всех случаях клиентские приложения получают одни и те же данные (клиент 3), поэтому универсальный код ресурса (URI) фактически не должен отличаться в зависимости от версии. Also, from a purist’s point of view, in all cases the client applications are fetching the same data (customer 3), so the URI should not really be different depending on the version. Эта схема также усложняет реализацию HATEOAS, поскольку потребуется включать номер версии в универсальные коды ресурсов (URI) всех ссылок. This scheme also complicates implementation of HATEOAS as all links will need to include the version number in their URIs.

    Управление версиями через строку запроса Query string versioning

    Чтобы не указывать множество кодов URI, вы можете указать версию ресурса с помощью параметра в строке запроса, добавленного к HTTP-запросу, например https://adventure-works.com/customers/3?version=2 . Rather than providing multiple URIs, you can specify the version of the resource by using a parameter within the query string appended to the HTTP request, such as https://adventure-works.com/customers/3?version=2 . Значение по умолчанию параметра версии должно быть содержательным, например 1, если оно опускается клиентскими приложениями прежних версий. The version parameter should default to a meaningful value such as 1 if it is omitted by older client applications.

    Этот подход обладает семантическим преимуществом в том плане, что один и тот же ресурс всегда возвращается по одинаковому универсальному коду ресурса (URI). Однако он зависит от кода, обрабатывающего запрос для анализа строки запроса и возврата соответствующего HTTP-ответа. This approach has the semantic advantage that the same resource is always retrieved from the same URI, but it depends on the code that handles the request to parse the query string and send back the appropriate HTTP response. Кроме того, этот подход также усложняет реализацию HATEOAS, как и механизм управления версиями через универсальные коды ресурсов (URI). This approach also suffers from the same complications for implementing HATEOAS as the URI versioning mechanism.

    Некоторые браузеры прежних версий и веб-прокси не могут кэшировать ответы по запросам, содержащим строку запроса в URL-адресе. Some older web browsers and web proxies will not cache responses for requests that include a query string in the URI. Это может привести к снижению производительности веб-приложений, использующих веб-API и запускаемых из такого веб-браузера. This can degrade performance for web applications that use a web API and that run from within such a web browser.

    Управление версиями через заголовок Header versioning

    Вместо того чтобы добавлять номер версии в виде параметра строки запроса, вы можете реализовать пользовательский заголовок, указывающий версию ресурса. Rather than appending the version number as a query string parameter, you could implement a custom header that indicates the version of the resource. Этот подход требует от клиентского приложения добавления соответствующего заголовка во все запросы. При этом в коде, обрабатывающем запрос клиентского приложения, можно использовать значение по умолчанию (версия 1), если заголовок с номером версии опускается. This approach requires that the client application adds the appropriate header to any requests, although the code handling the client request could use a default value (version 1) if the version header is omitted. В следующих примерах используется пользовательский заголовок с именем Custom-Header. The following examples use a custom header named Custom-Header. Значение этого заголовка указывает версию веб-API. The value of this header indicates the version of web API.

    Версия 1: Version 1:

    Версия 2: Version 2:

    Как и в предыдущих двух подходах, реализация HATEOAS требует включения соответствующего пользовательского заголовка в любые ссылки. As with the previous two approaches, implementing HATEOAS requires including the appropriate custom header in any links.

    Управление версиями через тип носителя Media type versioning

    При отправке HTTP-запроса GET на веб-сервер клиентское приложение должно указывать поддерживаемый формат содержимого с помощью заголовка «Accept», как описано ранее в этом руководстве. When a client application sends an HTTP GET request to a web server it should stipulate the format of the content that it can handle by using an Accept header, as described earlier in this guidance. Нередко заголовок Accept используется для того, чтобы позволить клиентскому приложению указать требуемый формат текста ответа: XML, JSON или другой формат, который клиентское приложение может анализировать. Frequently the purpose of the Accept header is to allow the client application to specify whether the body of the response should be XML, JSON, or some other common format that the client can parse. Однако можно определить пользовательские типы носителей, которые содержат сведения, позволяющие клиентскому приложению указывать предпочтительную версию ресурса. However, it is possible to define custom media types that include information enabling the client application to indicate which version of a resource it is expecting. В следующем примере показан запрос, в котором используется заголовок Accept со значением application/vnd.adventure-works.v1+json. The following example shows a request that specifies an Accept header with the value application/vnd.adventure-works.v1+json. Элемент vnd.adventure-works.v1 указывает веб-серверу на необходимость возврата ресурса версии 1, в то время как элемент json указывает JSON в качестве предпочтительного формата текста ответа. The vnd.adventure-works.v1 element indicates to the web server that it should return version 1 of the resource, while the json element specifies that the format of the response body should be JSON:

    Код, обрабатывающий запрос, отвечает за обработку заголовка Accept и максимальное выполнение содержащихся в нем требований (клиентское приложение может указать в заголовке Accept несколько форматов, в случае чего веб-сервер может выбрать наиболее подходящий формат текста ответа). The code handling the request is responsible for processing the Accept header and honoring it as far as possible (the client application may specify multiple formats in the Accept header, in which case the web server can choose the most appropriate format for the response body). Веб-сервер подтверждает формат данных в тексте ответа с помощью заголовка «Content-Type»: The web server confirms the format of the data in the response body by using the Content-Type header:

    Если в заголовке «Accept» не указан ни один из известных типов носителя, веб-сервер может отправить ответное сообщение с кодом HTTP 406 (неприемлемо) или вернуть сообщение с типом носителя по умолчанию. If the Accept header does not specify any known media types, the web server could generate an HTTP 406 (Not Acceptable) response message or return a message with a default media type.

    Вероятно, это самый полноценный механизм управления версиями, беспрепятственно поддерживающий принцип HATEOAS, который может включать MIME-тип связанных данных в ссылках ресурсов. This approach is arguably the purest of the versioning mechanisms and lends itself naturally to HATEOAS, which can include the MIME type of related data in resource links.

    При выборе стратегии управления версиями вам также следует учесть воздействие на производительность, особенно при кэшировании на веб-сервере. When you select a versioning strategy, you should also consider the implications on performance, especially caching on the web server. Управление версиями через универсальные коды ресурсов (URI) и строку запроса поддерживает кэширование, поскольку одинаковое сочетание универсального кода ресурса (URI) и строки запроса каждый раз соотносится с одними и теми же данными. The URI versioning and Query String versioning schemes are cache-friendly inasmuch as the same URI/query string combination refers to the same data each time.

    Механизмы управления версиями через заголовок и тип носителя, как правило, требуют дополнительной логики для проверки значений в пользовательском заголовке или заголовке «Accept». The Header versioning and Media Type versioning mechanisms typically require additional logic to examine the values in the custom header or the Accept header. Использование многочисленными клиентами разных версий веб-API в крупномасштабной среде может привести к образованию большого объема повторяющихся данных в кэше на стороне сервера. In a large-scale environment, many clients using different versions of a web API can result in a significant amount of duplicated data in a server-side cache. Эта проблема может усложниться, если клиентское приложение обменивается данными с веб-сервером через прокси-сервер, реализующий кэширование, который перенаправляет запрос на веб-сервер лишь в том случае, если в его кэше на текущий момент не содержится копия запрашиваемых данных. This issue can become acute if a client application communicates with a web server through a proxy that implements caching, and that only forwards a request to the web server if it does not currently hold a copy of the requested data in its cache.

    Open API Initiative Open API Initiative

    Организация Open API Initiative создана отраслевым консорциумом для стандартизации описаний REST API разных поставщиков. The Open API Initiative was created by an industry consortium to standardize REST API descriptions across vendors. В рамках этой инициативы спецификация Swagger 2.0 была переименована в OpenAPI Specification (OAS) и перенесена в проект Open API Initiative. As part of this initiative, the Swagger 2.0 specification was renamed the OpenAPI Specification (OAS) and brought under the Open API Initiative.

    Возможно, вам потребуется применить OpenAPI для вашего веб-API. You may want to adopt OpenAPI for your web APIs. Учитывайте следующие факторы. Some points to consider:

    Спецификация OpenAPI поставляется с набором заключений и рекомендаций по разработке REST API. The OpenAPI Specification comes with a set of opinionated guidelines on how a REST API should be designed. Она дает ряд преимуществ для взаимодействия, но требует дополнительного внимания при разработке API для соблюдения спецификации. That has advantages for interoperability, but requires more care when designing your API to conform to the specification.

    В OpenAPI рекомендуется начинать работу с создания контракта, а не реализации. OpenAPI promotes a contract-first approach, rather than an implementation-first approach. Это означает, что при разработке API вы сначала создаете контракт (интерфейс) и лишь после этого пишете код для его реализации. Contract-first means you design the API contract (the interface) first and then write code that implements the contract.

    При помощи Swagger и других средства можно создавать клиентские библиотеки и документацию на основе контрактов API. Tools like Swagger can generate client libraries or documentation from API contracts. Например, см. веб-API ASP.NET страниц справки с помощью Swagger. For example, see ASP.NET Web API help pages using Swagger.

    Дополнительные сведения More information

    Рекомендации корпорации майкрософт REST API. Microsoft REST API guidelines. Подробные рекомендации по разработке общедоступных REST API. Detailed recommendations for designing public REST APIs.

    Контрольный список веб-API. Web API checklist. Список факторов, которые следует учитывать при разработке и реализации веб-API. A useful list of items to consider when designing and implementing a web API.

    Open API Initiative. Open API Initiative. Документация и сведения о реализации Open API. Documentation and implementation details on Open API.

    Топ-пост этого месяца:  Числа в JavaScript. Функция parseInt
    Добавить комментарий