Правила именования ресурсов

Ресурс — это единица информации в терминологии REST API. Ресурсом может быть документ, один пост в блоге, или список постов, пользователь социальной сети — всё, к чему можно обратиться при HTTP-запросе. Это концептуальное отображение какого-то объекта или набора объектов, но не сами эти объекты. Мы отображаем данные в текстовом формате, чтобы выполнять с ними какие-то действия.
JSON и XML — это форматы данных для текстового представления ресурсов.

Правила именования ресурсов

Для обращения к ресурсам через HTTP-запросы их необходимо как-то именовать. Чем понятнее имена ресурсов, тем проще разобраться в API. Здорово, когда по названию ресурса можно понять, что он содержит.
Чтобы с вашим API было просто и удобно общаться — соблюдайте простые правила.

Ресурсы — существительные

Почти всегда ресурсы именуют существительными во множественном числе:
Скопировать код
https://praktikum.ru/users
Скопировать код
https://swapi.co/api/starships
Перед вами API звёздных войн. Попробуйте догадаться, какой список объектов вернет GET-запрос на https://swapi.co/api/starships?
Иногда для именования ресурсов применяют единственное число, но это реже:
Скопировать код
https://praktikum.ru/users/{user-id}/profile
https://praktikum.ru/users/me
Иногда можно выбрать глагол в качестве имени. Но такое имя бывает удачным крайне редко:
Скопировать код
https://praktikum.ru/users/{user-id}/cart/checkout # проверка корзины
https://praktikum.ru/login # для получения токена
https://praktikum.ru/refresh # для обновления токена

Слэш для иерархии

Слэш в URL используется для указания иерархии ресурсов по принципу «от общего к частному»:
Скопировать код
GET /users/{user-id}/posts
Все пользователи → Конкретный пользователь по ID → Все его посты
То есть запрос вернет посты конкретного пользователя. Если мы хотим получить конкретный пост — нужно указать его ID:
Скопировать код
GET /users/{user-id}/posts/{post-id}

«Висящий» слэш — не рекомендуется

Висящий слэш в конце URL не добавляет информации. Лучше избегать такого употребления.
Скопировать код
// не надо так
GET /users/{user-id}/posts/

// лучше вот так
GET /users/{user-id}/posts

Дефисы вместо пробелов

В URL не должно быть пробелов, их заменяют либо дефисами, либо нижними подчёркиваниями. Дефисы лучше, потому что:
  • на некоторых устройствах нижнее подчёркивание может выйти за базовую линию строки, и его будет не видно вовсе;
  • несколько нижних подчёркиваний сливаются в одно.
Скопировать код
// делайте так:
GET /users/{user-id}/user-devices

// а не так:
GET /users/{user-id}/user_devices

HTTP-методы

Любой API предназначен для получения доступа к ресурсам сервера. К ресурсу всегда можно обратиться по URL.
HTTP-метод запроса определяет, что следует сделать:
  • GET получает ресурсы;
  • POST создаёт ресурс;
  • PUT заменяет существующий ресурс целиком;
  • PATCH частично изменяет существующий ресурс;
  • DELETE удаляет ресурс.
Реже применяют ещё два метода:
  • HEAD, получить только заголовки ответа. HEAD похож на GET, но у его ответа нет тела;
  • OPTIONS, узнать, какие HTTP-методы поддерживает сервер.
Сам по себе метод не определяет логику работы сервера. Можно закодить API так, чтобы запрос POST удалял ресурс, а DELETE — добавлял. Поступайте именно так, когда вам поставят задачу «нарушить как можно больше стандартов и усложнить работу коллегам».

HTTP-методы — это глаголы

Используйте HTTP-методы для указания совершаемого над ресурсом действия:
Скопировать код
// получить список пользователей
GET /users

// создать пользователя
POST /users

// удалить пользователя с id = 2
DELETE /users/2
А включать в название имя HTTP-метода не стоит:
Скопировать код
# так не надо
GET /get-users
POST /create-user
Из названия HTTP-метода уже понятно, что делать с ресурсом, не нужно дублировать задание.

Идемпотентность и безопасность методов

У методов есть две характеристики — безопасность и идемпотентность.
Безопасность: если метод может изменить ресурс, то он считается небезопасным в терминах архитектуры REST. Такими методами могут быть PUT, PATCH, DELETE или POST.
Идемпотентность метода заключается в том, что его многократное повторение равно однократному. То есть выполняя один и тот же запрос много-много раз, мы всегда будем получать один и тот же результат.
Выберите верные утверждения.