Как правильно составлять путь к ресурсу?

Большинство знает эти правила на интуитивном уровне, но не лишним будет структурировать эти знания

Ресурс в RESTful API представляет собой сущность, с которой взаимодействуют клиенты. Примеры ресурсов включают пользователей (users), заказы (orders) и товары (products).

Основные правила

〰️ Используйте существительные: Путь к ресурсу должен быть представлен существительным в единственном числе. Это подчеркивает, что ресурс идентифицируется уникальным образом

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

〰️ Идентификация конкретного экземпляра ресурса: Если вы хотите обратиться к конкретному элементу ресурса, используйте уникальный идентификатор после слэша.
/users/{id}
/orders/{order_id}

〰️ Вложенность ресурсов. Если ресурсы имеют иерархию, отражайте её в пути. Например, заказы принадлежат пользователям, поэтому заказ можно вложить в пользователя:
/users/{user_id}/orders


🧮 Если нужно обратиться к коллекции ресурсов
Когда вам нужно оперировать коллекциями ресурсов, используйте множественное число:
/users
/products

Рекомендации
🧲 Стремитесь сохранять единообразие в именовании и структуре путей. Если один ресурс использует определённый шаблон, старайтесь применять этот шаблон ко всем другим ресурсам.
🧲 Минимизируйте количество уровней вложенности: Чем короче путь, тем проще ориентироваться посетителям и быстрее индексироваться поисковиками.
🧲 Следите за согласованностью стилей: Старайтесь избегать использования транслита или кириллицы там, где возможны проблемы совместимости.

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