Приближение второе: правильный путь Если вы вдруг пропустили первое приближение, его можно найти Здесь .Теги: #webapi #rest #api #rest api #apiИ в этом подходе хотелось бы отдельно поговорить о подходах к построению уникальных путей к ресурсам и методам вашего веб-API и о тех архитектурных особенностях приложения, которые влияют на внешний вид этого пути и его компонентов.
О чем стоит подумать, стоя на берегу
Управление версиями
Рано или поздно любая операционная система начинает развиваться: развиваться, усложняться, масштабироваться, становиться более современной.Для разработчиков REST API это чревато, прежде всего, необходимостью запускать новые версии API при работе старых.
Здесь я говорю уже не об архитектурных изменениях под капотом вашей системы, а о том, что меняется сам формат данных и набор операций с ними.
В любом случае версионирование должно быть предусмотрено как при первоначальной организации исходного кода, так и в принципе построения URL. Когда дело доходит до URL-адресов, существует два наиболее популярных способа указать версию API, к которому адресован запрос.
Префикс пути пример-api.com/v1/ и управление версиями на уровне субдомена v1.example-api.com .
Вы можете использовать любой из них, в зависимости от ваших потребностей и требований.
Автономность компонентов
Веб-API сложных систем, поддерживающих несколько ролей пользователей, часто требует разделения на части, каждая из которых выполняет свой спектр задач.Фактически каждая часть может быть независимым приложением, работающим на разных физических машинах и платформах.
В контексте описания API нам совершенно не важно, как сервер обрабатывает запрос и какие силы и технологии при этом задействованы.
Для клиента API — это инкапсулированная система.
Однако разные части системы могут иметь совершенно разный функционал, например, административная и пользовательская часть.
Да и методология работы с, казалось бы, одинаковыми ресурсами может существенно отличаться.
Поэтому такие части необходимо разделять на уровне домена.
admin.v1.example-api.com или префикс пути пример-api.com/v1/admin .
Это требование не является обязательным и многое зависит от сложности системы и ее назначения.
Формат обмена данными
Самый удобный и функциональный, на мой взгляд, формат обмена данными — JSON , но никто не запрещает использовать XML , ЯМЛ или любой другой формат, позволяющий хранить сериализованные объекты без потери типа данных (мы за типизацию).При желании вы можете заставить API поддерживать несколько форматов ввода/вывода.
Достаточно использовать заголовок HTTP-запроса, чтобы указать желаемый формат ответа.
Принимать И Тип содержимого для указания формата данных, отправляемых в запросе.
Другой популярный способ — добавить расширение к URL-адресу ресурса, например.
ПОЛУЧИТЬ /users.xml , но этот метод кажется менее гибким и красивым хотя бы потому, что он утяжеляет URL и справедлив скорее для GET-запросов, чем для всех возможных операций.
Локализация и многоязычие
На практике мультиязычность API чаще всего сводится к переводу служебных сообщений и сообщений об ошибках на необходимый язык для непосредственного отображения конечному пользователю.Многоязычный контент тоже имеет свое место, но сохранение и выдача контента на разных языках, на мой взгляд, следует разграничивать более четко, например, если у вас одна и та же статья на разных языках, то по сути это две разные сущности, сгруппированные по признак единства содержания.
Для определения ожидаемого языка можно использовать различные методы.
Самый простой — стандартный HTTP-заголовок.
Accept-Язык .
Я видел другие методы, такие как добавление параметра GET Language="en" с использованием префикса пути.
пример-api.com/en/ или даже на уровне доменного имени ru.example-api.com .
Мне кажется, выбор способа указания локали зависит от конкретного приложения и стоящих перед ним задач.
Внутренняя маршрутизация
Итак, мы достигли корневого узла нашего API (или одного из его компонентов).Все дальнейшие маршруты будут проходить непосредственно внутри вашего серверного приложения, в соответствии с набором поддерживаемых им ресурсов.
Пути сбора
Чтобы указать путь к коллекции, мы просто используем имя соответствующей сущности, например, если это список пользователей, то путь будет такой /пользователи .К коллекции как таковой применяются два метода: ПОЛУЧАТЬ (получение ограниченного списка субъектов) и ПОЧТА (создание нового элемента).
В запросах списков мы можем использовать множество дополнительных GET-параметров, используемых для разбиения на страницы, сортировки, фильтрации, поиска и т. д., но они должны быть необязательными, т.е.
эти параметры нельзя передавать как часть пути!
Ээлементы коллекции
Чтобы получить доступ к определенному элементу коллекции, мы используем его уникальный идентификатор в маршруте./пользователи/25 .
Это уникальный путь к нему.
Методы используются для работы с объектом.
ПОЛУЧАТЬ (получение предмета), СТАВИТЬ/ИСПРАВИТЬ (изменить) и УДАЛИТЬ (удаление).
Уникальные объекты
Многие сервисы имеют объекты, уникальные для текущего пользователя, например профиль текущего пользователя./профиль или личные настройки /настройки .
Конечно, с одной стороны, это элементы одной из коллекций, но они являются отправной точкой использования нашего Web API клиентским приложением, а также позволяют выполнять гораздо более широкий спектр операций над данными.
Однако коллекция, в которой хранятся пользовательские настройки, может быть вообще недоступна из соображений безопасности и конфиденциальности данных.
Свойства объектов и коллекций
Для того, чтобы напрямую добраться до любого из свойств объекта, достаточно добавить в путь к объекту имя свойства, например, получить имя пользователя /users/25/name. Методы применимы к объекту ПОЛУЧАТЬ (получение значения) и СТАВИТЬ/ИСПРАВИТЬ (изменение стоимости).Метод УДАЛИТЬ неприменимо, поскольку свойство является структурной частью объекта, как формализованной единицей данных.
В предыдущей части мы говорили о том, что коллекции, как и объекты, могут иметь свои свойства.
По моему опыту, единственное свойство, которое я нашел полезным, — это свойство count, но ваше приложение может быть более сложным и специфичным.
Пути к свойствам коллекций строятся по тому же принципу, что и к свойствам их элементов: /users/count. Для свойств коллекции применим только метод ПОЛУЧАТЬ (получение свойства), поскольку коллекция — это всего лишь интерфейс доступа к списку.
Коллекции связанных объектов
Одним типом свойства объекта могут быть связанные объекты или коллекции связанных объектов.Такие сущности, как правило, не являются собственным свойством объекта, а лишь ссылками на его связи с другими сущностями.
Например, список ролей, назначенных пользователю.
/пользователи/25/роли .
Подробно о работе с вложенными объектами и коллекциями мы поговорим в одной из следующих частей, но на данном этапе нам достаточно того, что у нас есть возможность обращаться к ним напрямую, как к любому другому свойству объекта.
Функции объектов и коллекций
Для построения пути к интерфейсу вызова функций коллекции или объекта мы используем тот же подход, что и для доступа к свойству.Например, для объекта /users/25/sendPasswordReminder или коллекции /пользователи/disableOld .
Для вызовов функций мы всегда используем метод POST. Почему? Напомню, что в классическом REST нет специального глагола для вызова функций, поэтому нам придется использовать один из существующих.
На мой взгляд, для этого больше всего подходит метод POST, потому что.
он позволяет передать необходимые аргументы серверу, не является идемпотентным (возвращающим один и тот же результат при многократном обращении) и наиболее абстрактным по семантике .
Надеюсь, что всё более-менее вписывается в систему :) В следующей части мы подробнее поговорим о запросах и ответах, их форматах и кодах статусов.
-
Redhat Блокирует Российские Аккаунты
19 Oct, 24 -
Можно Ли Запрограммировать Случайность?
19 Oct, 24 -
Дизайнеры! Умеешь Ли Ты Рисовать От Руки?
19 Oct, 24 -
Plastic Logic Reader Поддержали Газетчики
19 Oct, 24 -
Amazon Отверг Google
19 Oct, 24
