Именование ресурсов

Кроме правильного использования HTTP глаголов, именование ресурсов, вероятно, самая обсуждаемая и важная концепция для понимания во время создания понятного и легко используемого API для Web-сервиса. Когда ресурсы названы хорошо, API интуитивен и лёгок в использовании. Если же ресурсы названы плохо, тот же самый API может показаться неуклюжим и трудным в понимании и использовании. Ниже приведены несколько подсказок, как продолжить создавать URI ресурсов для нового API.

Фактически RESTful API - это всего лишь набор URI, HTTP вызовов к этим URI и некоторое количество представлений ресурсов в формате JSON и/или XML, многие из которых будут содержать перекрестные ссылки. За основу адресации берется покрытие уникальными идентификаторами ресурсов (URI) У каждого ресурса есть свой адрес или URI: вся интересная информация, которую сервер может предоставить, представлена как ресурс. Ограничение однообразия интерфейса частично реализовано с помощью комбинаций URI и HTTP глаголов и их использованием в соответствии со стандартами и конвенциями.

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

Ниже приведены примеры ресурсов:

Пользователи системы.
Курсы, в которых зарегистрирован студент.
История сообщений пользователя.
Пользователь, который подписан на другого пользователя.
Пользователи, которые подписаны на другого пользователя.
Статья о верховой езде.

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

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

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

Чтобы создать нового покупателя в системе мы используем:
POST http://www.example.com/customers

Чтобы получить информацию о покупателе с ID# 33245:
GET http://www.example.com/customers/33245 Тот же URI мы используем для PUT и DELETE, чтобы обновлять и удалять, соответственно.

Ниже предложены URI для продуктов:
POST http://www.example.com/products для создания нового продукта.

GET|PUT|DELETE http://www.example.com/products/66432
для чтения, обновления, удаления продукта с ID# 66432, соответственно.

Теперь становится весело… Как насчёт создания нового заказа у покупателя? Один вариант - POST http://www.example.com/orders. Это может работать для создания заказа, но здесь, пожалуй, не учитывается покупатель.

Поскольку мы хотим создать заказ для покупателя, (заметьте связь), этот URI, очевидно, не так интуитивен, как мог бы быть. Очевидно, что следующий URI предлагает большую ясность: POST http://www.example.com/customers/33245/orders Теперь мы знаем, что создаём заказ для покупателя с ID# 33245.

Что же вернет следующее?
GET http://www.example.com/customers/33245/orders
Вероятно, список заказов покупателя #33245. Заметьте: мы можем не поддерживать DELETE или PUT для этого URL, поскольку он оперирует коллекцией.

Теперь, продолжая концепцию иерархичности, как насчёт следующего URI?
POST http://www.example.com/customers/33245/orders/8769/lineitems
Это может добавлять отдельную позицию в заказ #8769 (который принадлежит покупателю #33245). Точно! GET на этот URI вернет все отдельные позиции данного заказа. Как бы то ни было, если отдельные позиции нельзя рассматривать только в контексте покупателя, или их можно рассматривать вне его контекста, мы можем предложить POST www.example.com/orders/8769/lineitems.

Наряду с этими строками, поскольку может быть несколько URI для заданного ресурса, мы также можем предложить GET http://www.example.com/orders/8769, который возвращает информацию о заказе по его ID без указания ID покупателя

Спускаясь глубже по иерархии:
GET http://www.example.com/customers/33245/orders/8769/lineitems/1
Может возвращать только первую отдельную позицию в заказе.

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

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

Twitter: https://dev.twitter.com/docs/api
Facebook: http://developers.facebook.com/docs/reference/api/
LinkedIn: https://developer.linkedin.com/apis

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

Прежде всего, часто сервисы используют один URI, чтобы определить интерфейс, используя строковые параметры jquery для определения операции, которую нужно выполнить и/или HTTP глагол. Например, чтобы обновить данные покупателя с ID 12345 и получить их в формате JSON может быть использован такой запрос:

GET http://api.example.com/services?op=update_customer&id=12345&format=json

Теперь вы не станете так делать. Несмотря на то, что узел URL-адреса 'services' — существительное, он не является самодокументируемым, поскольку иерархия URI не одна и та же для всех запросов. Кроме того, он использует глагол GET, хотя выполняет обновление. Это контринтуитивно, опасно и вызывает много боли у клиентов.

Вот другой пример, который тоже выполняет обновление данных о покупателе:

GET http://api.example.com/update_customer/12345

И его злобный двойник:

GET http://api.example.com/customers/12345/update

Вы часто можете увидеть последний запрос в сервисах других разработчиков. Заметим, что разработчики стараются создавать RESTful ресурсы и кое-где заметен прогресс. Но лучше, когда вы можете увидеть глагол в URL. Заметьте также, что нам не нужно использовать фразу 'update' в URL, потому что мы можем довериться HTTP глаголу, чтобы сообщить об этой операции. Проясним, что следующий URL избыточен:

PUT http://api.example.com/customers/12345/update

И с PUT, и с 'update' в запросе, мы рискуем запутать потребителей нашего сервиса. Является ли 'update' ресурсом? Мы потратим некоторое время на выяснение этого. Я уверен, вы понимаете.

Давайте поговорим о споре между плюрализаторами и "сингуларизаторами". Вы не слышали об этом споре? Он существует. Соответственно, всё сводится в следующему вопросу:

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

GET http://www.example.com/customer/33245 или GET http://www.example.com/customers/33245

С обеих точек зрения приведены хорошие аргументы, но общепринятой практикой является плюрализация узлов, чтобы обеспечить согласованность для всех HTTP методов. Этот подход обоснован тем, что покупатели считаются коллекцией внутри сервиса и ID (например, 33245) ссылается на одного покупателя из коллекции.

Используя это правило, получим следующие URI с множеством узлов (выделено мной):

GET http://www.example.com/customers/33245/orders/8769/lineitems/1

ноды 'customers', 'orders', и 'lineitems' использованы во множественном числе.

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

POST http://www.example.com/customers

А для чтения, обновления и удаления следующий:

GET|PUT|DELETE http://www.example.com/customers/{id}

Как было замечено ранее, у ресурса может быть несколько URI, но для минимальных возможностей CRUD'а достаточно всего двух.

Вы можете спросить: есть ли ситуации, когда плюрализация не имеет смысла. Да, фактически есть. Когда в системе не требуется коллекция. Другими словами, приемлем singleton ресурс. Например, если есть единственный всеобъемлющий конфигурационный ресурс, вы можете использовать существительное в единственном числе, чтобы это отразить:

GET|PUT|DELETE http://www.example.com/configuration

Обратите внимание на отсутствие ID и использования глагола POST. Вы скажете, что если бы у каждого покупателя могла быть только одна конфигурация, тогда URL мог бы быть таким:

GET|PUT|DELETE http://www.example.com/customers/12345/configuration

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