Автоматизация для самых маленьких. заметки. restful api

Что такое REST?

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

REST – это не протокол и не реализация, а архитектурный стиль. За REST стоят некоторые базовые принципы, но в конечном итоге это не конкретная реализация, а абстракция.


REST ― это не столько конкретная конструкция или реализация, сколько архитектурный стиль. Как показано на , архитектура RESTful определяется простым набором ограничений. В основе RESTful-архитектуры лежит набор ресурсов. Эти ресурсы определяются своим URI (например, Uniform Resource Locator ) и внутренним представлением (обычно это форма самоописываемых данных, которые мы рассмотрим ниже). Наконец, существует набор операций, с помощью которых этими ресурсами можно управлять.

Рисунок 1. Общее представление архитектуры RESTful

На самом деле эти ресурсы могут представлять объекты данных с использованием различных типов (например, JavaScript Object Notation ). К ресурсам можно обращаться через URL-адреса (например, ) с использованием набора стандартных операций (, , и т.п.). Использование HTTP в качестве транспорта значительно упрощает разработку RESTful-архитектур, так как это известный и стабильный базовый протокол. К тому же HTTP широко доступен, и для его использования, в частности, в таких интернет-службах, как шлюзы, прокси, средства безопасности и службы кэширования HTTP, не требуется новая конфигурация. Чтобы добиться высокой масштабируемости серверов REST, можно использовать другие полезные возможности, такие как выравнивание нагрузки.

Принципы и ограничения RESTful

Архитектура REST основывается на нескольких характеристиках, которые описаны ниже. Любой RESTful веб-сервис должен им соответствовать, чтобы называться таковым. Эти характеристики также известны как принципы проектирования, которым нужно следовать при работе с RESTful-сервисами.

RESTful клиент-сервер

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

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

Отсутствие состояния

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

Кеш

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

Многослойная система

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

Единообразие интерфейса

Это фундаментальное требование дизайна RESTful-сервисов. RESTful работает на уровне HTTP и использует нижеприведённые методы для работы с ресурсами на сервере:

  • POST — для создания ресурса;
  • GET — для его получения;
  • PUT — для его обновления;
  • DELETE — для его удаления.

API-интерфейсы SOAP являются предшественниками REST API

До того, как REST стал самым популярным веб-сервисом, SOAP (Simple Object Access Protocol) был гораздо более распространенным. Чтобы лучше понять REST, полезно иметь некоторое понимание SOAP. Заодно и увидеть, что отличает SOAP и REST.

SOAP — это стандартизированный протокол, который требует XML в качестве формата сообщений для запросов и ответов. Как стандартный протокол, формат сообщения обычно определяется с помощью файла WSDL (язык описания веб-служб).

Файл WSDL определяет разрешенные элементы и атрибуты в обмениваемых сообщениях. Файл WSDL является машиночитаемым и используется серверами, взаимодействующими друг с другом для облегчения связи.

Сообщения SOAP заключены в «конверт», который включает в себя заголовок и тело, используя определенную схему XML и пространство имен. Пример формата запроса и ответа SOAP см. SOAP против REST 101: понимание различий.

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

SOAP по-прежнему используется в enterprise приложениях (особенно в финансовых учреждениях) со связью server-to-server, но в последние годы SOAP вымещается REST, особенно для API открытых сетей.

RESTful архитектура

Приложение или архитектура считается RESTful, если ей присущи следующие характеристики:

  1. Состояние и функциональность представлены в виде ресурсов — это значит, что каждый ресурс должен быть доступен через обычные HTTP-запросы GET, POST, PUT или DELETE. Так, если кто-то хочет получить файл на сервере, у них должна быть возможность отправить GET-запрос и получить файл. Если он хочет загрузить файл на сервер, то у него должна быть возможность использовать POST или PUT-запрос. Наконец, если он хочет удалить файл, должна быть возможность отправить запрос DELETE.
  2. Архитектура клиент-сервер, отсутствие состояния (stateless) и поддержка кеширования:
    • Клиент-сервер — обычная архитектура, где сервером может быть веб-сервер, на котором, на котором размещено приложение, а клиентом — обычный веб-браузер;
    • Архитектура без сохранения состояния означает, что состояние приложения не сохраняется в REST. Например, если вы удалили ресурс с сервера командой DELETE, то даже при получении положительного кода ответа нет гарантий, что он действительно был удалён. Чтобы убедиться, что ресурс удалён, необходимо отправить GET-запрос. С его помощью можно запросить ресурсы, чтобы посмотреть, присутствует ли там удалённый.

Самоописываемые данные

Сообщение между неоднородными системами приводит к некоторым интересным проблемам, одна из которых ― последовательное упорядочение данных для передачи. Машины представляют данные разными способами (от различных представлений с плавающей точкой до нестандартного порядка следования байтов). В число ранних реализаций входили формат Abstract Syntax Notation (ASN.1) и протокол External Data Representation (XDR) (используется в Network File System). К числу других подходов относится XML, который кодирует данные в текстовых документах ASCII.

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


А теперь рассмотрим пример JSON, в частности, его реализацию через REST-интерфейс CrunchBase. В этом примере используется интерактивная оболочка Ruby (), которая позволяет экспериментировать с Ruby в режиме реального времени.

Как показано в , сначала исполняется интерактивная оболочка Ruby. Для подготовки среды вам придется загрузить несколько модулей (в частности, компоненты JSON и HTTP) и определить свой URI. Заметим, что URI ― это полный запрос к CrunchBase (в пространстве имен company с постоянной ссылкой ). Он передается в метод класса , который выполняет запрос по указанному URI (разложенному на отдельные компоненты с помощью метода ). Если набрать , то можно увидеть возвращенные данные JSON. Это набор пар имя-значение (таких как name и IBM). Для преобразования ответа в объектную структуру Ruby используется метод . Наконец, извлекаем нужное значение, указав его имя.

Листинг 2. Обращение к базе денных CrunchBase с помощью Ruby
$ irb
irb(main):001:0> require 'rubygems'
=> true
irb(main):002:0> require 'json'
=> true
irb(main):003:0> require 'net/http'
=> true
irb(main):004:0> uri = "http://api.crunchbase.com/v/1/company/ibm.js"
=> "http://api.crunchbase.com/v/1/company/ibm.js"
irb(main):005:0> resp = Net::HTTP.get_response(URI.parse(uri))
=> #<Net::HTTPOK 200 OK readbody=true>
irb(main):006:0> puts resp.body
{"name": "IBM",
 "permalink": "ibm",
 "crunchbase_url": "http://www.crunchbase.com/company/ibm",
 "homepage_url": "http://www.ibm.com",
 "blog_url": "",
 "blog_feed_url": "",
 "twitter_username": "",
 "category_code": "software",
 "number_of_employees": 388000,
...
=> nil
irb(main):007:0> parsedresp = JSON.parse(resp.body)
=> {"updated_at"=>"Wed Feb 01 03:10:14 UTC 2012", "alias_list"=>nil, 
...
irb(main):008:0> 
irb(main):009:0* puts parsedresp
1896
=> nil
irb(main):010:0>

Из видно, как легко написать код для быстрого извлечения данных из ответа JSON (7 строк). Теперь пойдем дальше и построим простой универсальный API для взаимодействия с CrunchBase.

Создание класса, представляющего ресурс

Теперь, когда вы настроили проект и систему сборки, вы можете создать ваш web-сервис.

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

Сервис будет обрабатывать запросы для , дополнительно — параметр в строке запроса. запрос должен возвращать ответ со статусом и JSON в теле, которое соответствует сообщению приветствия. он должен выглядеть таким образом:

Поле — это уникальный идентификатор приветствия, а — текстовое представление.

Для модели представления приветствия вам необходимо создать класс, представляющего ресурс. Он представляет собой простой java-объект с полями, конструкторами и методами доступа к значениям и :

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

Модули курса

    • Коротко о курсе
    • Обзор курса
    • Для чего этот курс
    • Об авторе
    • Знакомство с документацией REST API
    • Что такое REST API
    • Видео презентации
    • Слайды курса
    • Практические занятия
    • Практика: Определение цели
    • Рынок документации REST API
    • Сценарий использования API погоды
    • Получение ключей авторизации
    • Отправка запросов в Postman
    • Введение и установка curl
    • Создание curl запроса
    • Понимание curl
    • Использование методов с curl
    • Анализ JSON ответов
    • Изучение полезных данных JSON ответа
    • Доступ и вывод на страницу определенного значения JSON
    • Погружение в точечную нотацию
    • Документирование новой конечной точки
    • Обзор пошагового описания API ссылки
    • Шаг 1: Описание ресурса
    • Шаг 2: Конечные точки и методы
    • Шаг 3: Параметры
    • Шаг 4: Пример запроса
    • Шаг 5: Пример и схема ответа
    • Собираем все вместе
    • Практическое занятие: Что не так в разделе API?
    • Практическое занятие: Поиск open-source проекта
    • Практическое занятие: Оценка ключевых элементов API документации
    • Обзор форматов спецификаций REST API
    • Знакомство со спецификациями OpenAPI и Swagger
    • Работа в YAML
    • Обзор руководства OpenAPI
    • Шаг 1: Объект
    • Шаг 2: Объект
    • Шаг3: Объект
    • Шаг 4: Объект
    • Шаг 5: Объект
    • Шаг 6: Объект
    • Шаг 7: Объект
    • Шаг 8: Объект
    • Практическое занятие: Создание спецификации OpenAPI
    • Руководство Swagger UI
    • Демо Swagger UI
    • Введение и руководство SwaggerHub
    • Stoplight — инструмент визуального моделирования для создания спецификаций
    • Интеграция Swagger с документацией
    • Обзор тестирования документации
    • Настройка тестовой среды окружения
    • Самостоятельное тестирование всех инструкций
    • Тестирование предположений
    • Практическое занятие: Тестирование документации проекта
    • Разделы руководства пользователя
    • Обзор API
    • Руководство по началу работы
    • Требования аутентификации и авторизации
    • Коды статусов и ошибок
    • Ограничения скорости
    • Описание и образцы кода
    • SDK и пример приложений
    • Краткое справочное руководство
    • API Глоссарий
    • Лучшие практики API
    • Практическое занятие: Оценка концептуального контента в проекте
    • Обзор вариантов публикации документации
    • Список из 100 сайтов с API документацией
    • Шаблоны проектирования сайтов API документации
    • Инструменты Docs-as-code
    • Подробнее о Markdown
    • Система контроля версий (пример Git)
    • Практическое занятие: Управляем контентом в Wiki Github
    • Практическое занятие: Используем клиент GitHub для десктопа
    • Практическое занятие: процесс Pull request на GitHub
    • Генераторы статичных сайтов
    • Варианты хостинга и развертывания
    • Возможности автономных CMS
    • Рекомендации — какой инструмент документирования выбирать
    • Непрерывное развертывание Jekyll и CloudCannon
    • Кейс для изучения: Переход на Docs-as-code
    • Рынок вакансий для технического писателя
    • Необходимое количество кода, которое нужно знать
    • Лучшие локации для работы
    • Обзор нативных библиотек API
    • Получаем пример Java проекта
    • Java Ускоренный курс
    • Практическое занятие: Генерация Javadoc из примера проекта
    • Теги Javadoc
    • Изучение вывода Javadoc
    • Редактирование тегов Javadoc
    • Doxygen, генератор документации для С++
    • Создание концептуальной документации при помощи исходных библиотек API
    • Глоссарий API документации
    • Практические занятия REST API
    • Практическое занятие: Получаем информацию о событии, используя API сервиса Eventbrite
    • Практическое занятие: Извлекаем галерею, используя API сервиса Flikr
    • Практическое занятие: Получаем скорость ветра, используя API сервиса Aeris Weather
    • Справочник RAML
    • Справочник API Blueprint
    • Описание ошибок
    • Почему документирование кода так сложно?
    • Исследования о документировании кода
    • Пять стратегий документирования кода

HTTP коды

В стандарте HTTP описано более 70 статус кодов. Хорошим тоном является использование хотя бы основных.

  • 200 – OK – успешный запрос. Если клиентом были запрошены какие-либо данные, то они находятся в заголовке и/или теле сообщения.
  • 201 – OK – в результате успешного выполнения запроса был создан новый ресурс.
  • 204 – OK – ресурс успешно удалён.
  • 304 – Not Modified – клиент может использовать данные из кэша.
  • 400 – Bad Request – запрос невалидный или не может быть обработан.
  • 401 – Unauthorized – запрос требует аутентификации пользователя.
  • 403 – Forbidden – сервер понял запрос, но отказывается его обработать или доступ запрещен.
  • 404 – Not found – ресурс не найден.
  • 500 – Internal Server Error – разработчики API должны стараться избежать таких ошибок.

Эти ошибки должны быть отловлены в глобальном catch-блоке, залогированы, но они не должны быть возвращены в ответе.

Чем обширнее набор кодов, который мы будем использовать, тем более понятный будет API, который мы создаём. Однако нужно учесть, что некоторые коды браузеры обрабатывают по-разному. Например, некоторые браузеры получив код ответа 307 сразу же выполняют редирект, а некоторые позволяют обработать такую ситуацию и отменить действие. Прежде чем использовать тот или иной код, необходимо полностью понимать, как он будет обрабатываться на клиентской стороне!

Более подробно о HTTP кодах можно почитать тут.

Тестируем веб-сервис

Выше мы увидели, как браузер делает GET-запрос для вызова . Давайте проверим другие сценарии.

1. GET Tutorial/TutorialId — при вызове этого RESTful API клиент должен получить , соответствующий переданному .

Для вызова просто добавьте строку «/1» в конце URL, чтобы получить http://localhost:51056/TutorialService.svc/Tutorial/1. После перехода по этой ссылке вы должны увидеть следующее:

В этот раз был вызван метод , который вернул туториал с индексом 1 — «Queues».

2. POST Tutorial/TutorialName — при вызове этого API клиент отправляет запрос на добавление переданного , который сервер должен добавить в список. В этот раз нам понадобится инструмент Fiddler, который можно бесплатно скачать с официального сайта.

Запустите Fiddler и выполните следующие действия:

  1. Переключитесь на вкладку Composer. Она используется для создания запросов, которые можно отравить любому веб-приложению;
  2. Установите тип запроса равным «POST», а в URL вставьте адрес сервиса, в нашем случае это http://localhost:51056/TutorialService.svc/Tutorial;
  3. В окне, где уже есть строка «User-Agent: Fiddler» добавьте строку «Content-Type: application/json». Наш сервис работает только с данными в формате JSON, помните?
  4. Осталось ввести данные в поле «Request Body». Наш метод для POST-запросов принимает параметр . Передавая строку , мы указываем, что хотим добавить в список значение «Trees».

Нажмите на кнопку «Execute». После этого нашему сервису будет отправлен запрос на добавление «Trees».


3. DELETE Tutorial/TutorialId — при вызове этого API клиент отправит запрос на удаление из списка , которое соответствует переданному .

Запустите Fiddler и выполните следующие действия:

  1. Переключитесь на вкладку Composer;
  2. Установите тип запроса равным «DELETE», а в URL вставьте адрес сервиса вместе с элемента, который хотите удалить. Если мы хотим удалить второй элемент, то адрес будет http://localhost:51056/TutorialService.svc/Tutorial/1.

Нажмите на кнопку «Execute», чтобы отправить DELETE-запрос на удаление элемента «Queues».

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

Подведём итоги

  • REST используется для создания легковесных, поддерживаемых и масштабируемых веб-сервисов;
  • Всё больше приложений переходят на RESTful архитектуру, что обусловлено большим количеством разнообразных устройств и перемещением многих приложений в облако;
  • Основные составляющие REST — ресурсы, которые располагаются на сервере, и методы GET, POST, PUT и DELETE, которые можно использовать для работы с этими ресурсами;
  • Для создания RESTful веб-сервисов можно использовать Visual Studio и .NET;
  • При проверке работы сервиса с запросами вроде POST, DELETE и PUT нужно использовать сторонний инструмент Fiddler, который позволяет посылать серверу запросы таких типов.

Причины роста API

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

Например, вместо того, чтобы создавать собственный поиск для поддержки своего веб-сайта, можно воспользоваться API сервиса поиска Algolia. Вместо того, чтобы создавать свой собственный платежный шлюз, можно интегрировать Stripe API. В качестве сервиса авторизации можно использовать . Вместо того, чтобы создавать собственную систему электронной коммерции, можно использовать Snipcart API.

Практически каждый сервис предоставляет свою информацию и инструменты через API. Jekyll, популярный генератор статических сайтов, не имеет всех компонентов, необходимых для запуска сайта. Здесь нет интеграции новостных рассылок, аналитики, поиска, комментирования, форм, чата, электронной коммерции, опросов или других систем. Вместо этого на своем сайте Jekyll можно подключить нужные сервисы. (CloudCannon собрал длинный список сервисов, которые можно интегрировать в свой сайт.)

Многие сайты используют все необходимые им сервисы через внешние API

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

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

Ответ

Ответ — это данные которые вернуться из API в ответ на запрос. Ответы от конечных точек управляются классом WP_REST_Response. Класс предоставляет разные способы взаимодействия с данными ответа.

Ответы могут возвращать разные данные, в том числе JSON объект ошибки:

{
	"code": "rest_missing_callback_param",
	"message": "Отсутствует параметр: reassign",
	"data": {
		"status": 400,
		"params": 
	}
}

В заголовках ответа также указывается его статус код (200, 401). В REST API статус код часто важен, на его основе можно понять что не так с запросом. Подробнее про статус коды смотрите в отдельном разделе.

Некоторые важные моменты для реализации REST-клиента под Android, согласно паттернам A/B/C

  • Данные, полученные от REST-сервера, всегда сохраняются в sqlite. Напрямую в Activity они никогда не передаются. Вместо этого в Activity передается уведомление о том, что данные загружены в sqlite и их можно оттуда загрузить (вариант — Activity получает уведомление об обновлении данных в Content Provider через Content Observer).
  • При выполнении операций insert, delete, update данные в sqlite обновляются дважды: первый раз до отправки REST-запроса, второй раз — после получения результата. Первая операций выставляет информационные флаги, сигнализирующие о типе операции, проводимой над данными, и о статусе операции.
  • REST-методы следует всегда выполнять в отдельном потоке.
  • Следует использовать Apache HTTP client, а не Java URL connection.
  • Форматы данных в порядке предпочтения: какой-либо бинарный формат (например, AMF3), затем JSON, затем XML.
  • Желательно включать gzip. GZip на Android реализован “нативно”, библиотека быстрая. В некоторых случаях можно получить коэффициент сжатия 5:1 и даже 10:1, в зависимости от количества получаемых данных. Использование GZip ускоряет загрузку данных и экономит батарею.
  • Если используете Sqlite — используйте транзакции.
  • Если программе требуется скачать 10-20 картинок, не стоит запускать 10-20 параллельных закачек. Запускайте 1-3, а остальные ставьте в очередь.
  • Activity регистрирует binder callback (т.е. ResultReceiver), для получения ответа от сервиса. Этот callback нужно обязательно удалить при вызове onPause у Activity, иначе можно налететь на ANR.
  • Длительные операции всегда следует запускать из сервиса. Сервис обязательно следует останавливать после того, как требуемые операции выполнены.
  • Необходимо минимизировать сетевой трафик.
  • Следует разбивать данные на страницы (конечно, если REST Api предоставляют такую возможность).
  • Для некритичной по времени синхронизации данных между клиентом и сервером рекомендуется использовать SyncAdapter.

Guiding Principles of REST

  1. Client–server – By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.
  2. Stateless – Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
  3. Cacheable – Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
  4. Uniform interface – By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.
  5. Layered system – The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.
  6. Code on demand (optional) – REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.

Resource Methods

Another important thing associated with REST is resource methods to be used to perform the desired transition. A large number of people wrongly relate resource methods to HTTP GET/PUT/POST/DELETE methods.

Roy Fielding has never mentioned any recommendation around which method to be used in which condition. All he emphasizes is that it should be uniform interface. If you decide HTTP POST will be used for updating a resource – rather than most people recommend HTTP PUT – it’s alright and application interface will be RESTful.

Ideally, everything that is needed to change the resource state shall be part of API response for that resource – including methods and in what state they will leave the representation.

Another thing which will help you while building RESTful APIs is that query based API results should be represented by a list of links with summary information, not by arrays of original resource representations because the query is not a substitute for identification of resources.

Название сервиса

Для начала необходимо выбрать имя для REST сервиса. Под именем сервиса я подразумеваю его путь в URI запросе. Например, http://my-site.by/api/rest/service/name. Для выбора имени нам нужно понимать что такое “ресурсы” в архитектуре REST.

Представление ресурса


В терминологии REST что угодно может быть ресурсом — HTML-документ, изображение, информация о конкретном пользователе и т.д. Если ресурс представляет собой некоторый объект, его легко представить, используя некоторый стандартный формат, например, XML или JSON. Далее сервер может отправить данный ресурс, используя выбранный формат, а клиент сможет работать с полученным от сервера ресурсом, используя этот же формат.

Пример представления ресурса “профиль” в формате JSON:

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

  • Клиент и сервер должны “понимать” и иметь возможность работать с выбранным форматом.
  • Ресурс можно полностью описать, используя выбранный формат независимо от сложности ресурса.
  • Формат должен предусматривать возможность представления связей между ресурсами.

Пример представления ресурса “заказ” и его связи с ресурсом “профиль”:

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

Обращение к ресурсу

Каждый ресурс должен быть уникально обозначен постоянным идентификатором. «Постоянный» означает, что идентификатор не изменится за время обмена данными, и даже когда изменится состояние ресурса. Если ресурсу присваивается другой идентификатор, сервер должен сообщить клиенту, что запрос был неудачным и дать ссылку на новый адрес. Каждый ресурс однозначно определяется URL. Это значит, что URL по сути является первичным ключом для единицы данных. То есть, например, вторая книга с книжной полки будет иметь вид /books/2, а 41 страница в этой книге — /books/2/pages/41. Отсюда и получается строго заданный формат. Причем совершенно не имеет значения, в каком формате находятся данные по адресу /books/2/pages/41 – это может быть и HTML, и отсканированная копия в виде jpeg-файла, и документ Word.

Рекомендуется при определении имени REST-сервиса использовать имена ресурсов во множественном числе. Такой подход позволяет добавлять новые REST-сервисы лишь расширяя имена уже существующих. Например, сервис /books вернёт нам список всех книг, /books/3 вернёт информацию о 3-ей книге, а сервис /books/3/pages вернёт все страницы 3-ей книги.

Для сервисов, которые выполняют какие-то специфические действия над ресурсом, есть 2 подхода для указания действия: в имени сервиса или в его параметрах. Например, /books/3/clean или /books/3?clean. Я предпочитаю первый вариант, так как обычно такие сервисы не редко используют POST методы, которые не поддерживают передачу параметров в URl, что делает сервис, на мой взгляд, не очень читабельным. Используя определение типа действия в имени сервиса, мы делаем наш сервис более расширяемым, так как он не зависит от типа HTTP метода.

Также очень не рекомендуется использовать имена, включающие в себя несколько слов и описывающие бизнес составляющую сервиса (как это рекомендуется делать при именовании java методов). Например, вместо /getAllCars лучше сделать метод /cars. Если же метод нельзя никак описать одним словом, то необходимо применять единый стиль разделителей, я обычно использую ‘-’, что является наиболее популярным подходом. Например, /cars/3/can-sold.

Документация API — новинка для технических писателей

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

  • инструменты создания документации;
  • целевая аудитория;
  • языки программирования;
  • тематические разделы;
  • пользовательские задачи.

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

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

HTTP Методы

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

Методы которые используются в WP API:

  • GET — используются для получения (чтения) ресурсов (например постов).
  • POST — для создания ресурсов.
  • POST/PUT/PATCH — для обновления ресурсов.
  • DELETE — для удаления ресурсов.
  • OPTIONS — для получения полного описания маршрута.

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

Поэтому в WP API есть возможность указать такой метод по-другому:

  • в параметре запроса _method.
  • или в заголовке запроса X-HTTP-Method-Override.

Например, если нужно удалить ресурс, но для Клиента невозможно указать метод , то запрос можно отправить методом GET или POST, а сам метод передать в URL так: . _method параметр имеет больший приоритет над реальным методом запроса и в этом случае WP API будет обрабатывать запрос как если бы он был отправлен методом .


С этим читают