Руководство по именованию REST ресурсов

Руководство по именованию REST ресурсов

Примечание: данная статья является переводом. Оригинал можно прочитать здесь

В REST первичное представление данных называется ресурсом. Наличие строгой и последовательной стратегии именования ресурсов REST, определённо будет доказательством одного из лучших дизайнерских решений в долгосрочной перспективе.

Ресурс может быть одним элементом или коллекцией. Например, customers (клиенты) - это ресурс-коллекция, а customer (клиент) - ресурс-элемент. Мы можем идентифицировать ресурс коллекции customers, используя URI /customers, а ресурс одного клиента customer с помощью URI /customers/{customerId}.

Ресурс также может содержать вложенные коллекции. Например, вложенная коллекция accounts конкретного клиента (customer) может быть идентифицирована с использованием URI /customers/{customerId}/accounts. Аналогичным образом, одноэлементный ресурс account внутри вложенного ресурса accounts можно определить следующим образом: /customers/{customerId}/accounts/{accountId}.

Для управления ресурсами REST API использует URI (унифицированные идентификаторы ресурсов). Разработчики REST API должны создавать URI, которые чётко передают модель ресурсов потенциальным разработчикам клиентских приложений. Когда ресурсы названы хорошо, API является интуитивно понятным и простым в использовании. Если же это будет сделано плохо, API может оказаться трудным в использовании и понимании.

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

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

Лучшие практики именования REST ресурсов

Используйте существительные для представления ресурсов

RESTful URI должен ссылаться на ресурс, который является предметом (существительным), а не ссылкой на действие (глагол), поскольку существительные обладают свойствами, которых нет у глаголов - подобно тому, как у ресурсов есть некие атрибуты. Несколько примеров ресурсов:

  • пользователи системы
  • учётные записи пользователей
  • сетевые устройства и т.д.

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

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{id}

 

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

Документ

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

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

http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

 

Коллекция

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

Используйте название во множественном числе для обозначения архетипа ресурса-коллекции:

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts

 

Хранилище

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

Используйте названия в множественном числе для обозначения архетипа ресурса хранилища:

http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists

 

Контроллер

Ресурс-контроллер моделирует процедурную концепцию. Контроллеры похожи на исполняемые функции с параметрами и возвращаемыми значениями.

Используйте глагол для обозначения архетипа контроллера:

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

 

Последовательность и согласованность – ключевые понятия

Используйте соглашения об именовании и форматировании URI для минимальной двусмысленности и максимальной удобочитаемости и управляемости. Вы можете следовать нижеследующим советам для достижения согласованности.

1. Используйте слэш (/) для обозначения иерархических отношений

Символ слэша (/) используется для разделения URI на части, чтобы указать иерархическую взаимосвязь между ресурсами. Например:

http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

 

2. Не используйте в URI завершающий слэш

В качестве последнего символа в URI слэш не добавляет никакого семантического значения и может вызвать путаницу. Лучше отказаться от подобной практики.

http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices   // Эта версия гораздо лучше

 

3. Используйте дефисы для улучшения читаемости URI

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

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location

 

4. Не используйте нижние подчёркивания (_)

В качестве разделителя можно было бы использовать вместо дефиса и знак подчеркивания. Но в зависимости от шрифта приложения, возможно, что подчеркивания (_) могут быть частично закрыты или полностью скрыты в некоторых браузерах или не отображаться на некоторых экранах.

Чтобы избежать этой путаницы, используйте дефисы.

http://api.example.com/inventory-management/managed-entities // Хорошо читается
http://api.example.com/inventory_management/managed_entities // Более подвержен ошибкам

 

5. Используйте в URI буквы в нижнем регистре

Следует отдавать предпочтение строчным буквам в путях. При этом следует знать, что RFC 3986 определяет URI как чувствительные к регистру, за исключением схемы и компонентов хоста.

http://api.example.org/my-folder/my-doc  // 1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc  // 2
http://api.example.org/My-Folder/my-doc  // 3

 

Примеры 1 и 2 являются идентичными. Но путь в примере 3 отличается, поскольку использует заглавные буквы (My-Folder).

6. Не используйте расширения файлов

Расширения файлов выглядят плохо и не добавляют никаких преимуществ. Удаление их также уменьшает длину URI. Поэтому нет причин включать их в пути.

В случаях, когда Вы хотите указать, как нужно обрабатывать контент, не следует выделять медиа-тип с помощью расширений, лучше передать медиа-тип в заголовке Content-Type.

http://api.example.com/device-management/managed-devices.xml // Не делайте так
http://api.example.com/device-management/managed-devices     // Это корректный URI

 

Никогда не используйте в URI имена CRUD-функций

URI не должны использоваться для указания того, что выполняется функция CRUD. URI следует использовать для уникальной идентификации ресурсов, а не для каких-либо действий. А для указания функции CRUD должны использоваться методы HTTP-запроса.

HTTP GET http://api.example.com/devices   // Получить все устройства
HTTP POST http://api.example.com/devices  // Создать новое устройство

HTTP GET http://api.example.com/devices/{id}    // Получить устройство с указанным Id
HTTP PUT http://api.example.com/devices/{id}    // Обновить устройство с указанным Id
HTTP DELETE http://api.example.com/devices/{id} // Удалить устройство с указанным Id

 

Используйте компонент запроса для фильтрации коллекции URI

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

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ