REST API Проектирование путей запроса

[Elfix]

Приветствую!

Сделал несколько API для управления пользователями.

GET /api/users - получение списка пользователей;
GET /api/users/{userId} - получение полей выбранного пользователя;
POST /api/users - создание нового пользователя;
PATCH /api/users - изменение полей текущего пользователя;
PATCH /api/users/{userId} - изменение полей конкретного пользователя;
DELETE /api/users - удаление текущего пользователя;
DELETE /api/users/{userId} - удаление конкретного пользователя.

Есть еще желание сделать функционал получения, создания, редактирования, удаления адреса конкретного пользователя, но не понимаю в каком формате лучше это реализовать?

Нужно будет со временем получать список всех адресов, независимо от того, какому пользователю они принадлежат, или получать список адресов конкретного пользователя.

Я пока думаю о таком варианте:

GET /api/postalAddresses - получить список всех адресов;
GET /api/postalAddresses/{postalAddressId} - получить поля конкретного адреса;
GET /api/postalAddresses/users/{userId} - получить список адресов конкретного пользователя
GET /api/postalAddresses/{postalAddressId}/users/{userId} - получить поля конкретного адреса у конкретного пользователя.

Или такой вариант:

GET /api/users/postalAddresses - получить список всех адресов текущего пользователя
GET /api/users/{userId}/postalAddresses/ - получить список всех адресов конкретного пользователя
GET /api/users/{userId}/postalAddresses/{postalAddressId} - получить поля конкретного адреса у конкретного пользователя.

Таблица postalAddresses подчинена таблице users (postalAddresses.userId = users.id).

[ksa]

но не понимаю в каком формате лучше это реализовать?

Я за "второй" вариант...

[Elfix]

А как во втором варианте получить список всех адресов по всем пользователям?

[ksa]

Elfix, если такое нужно - сделай еще

GET /api/users/postalAddressesAll

[ksa]

Или вот это используй...

GET /api/postalAddresses - получить список всех адресов;

[Nexus]

А как во втором варианте получить список всех адресов по всем пользователям?

А кто запрещает совмещать различные варианты адресов?

GET /api/postalAddresses - получить список всех адресов;
GET /api/users/postalAddresses - получить список всех адресов текущего пользователя
GET /api/users/{userId}/postalAddresses/ - получить список всех адресов конкретного пользователя

Я бы только использовал в адресах не camelCase, а kebab-case или snake_case.

[Elfix]

Может есть какое то общепринятое соглашение, как обычно это форматируют? Стандарт или правила хорошего тона? В этом вопрос.

[Vlasenko Fedor]

я бы не писал адреса в верблюжей нотации
users/{userId}/postal-addresses читается легче
api - здесь префикc, apiv1, apiv2 ...
иначе не нужен

[ksa]

как обычно это форматируют?

Сильно зависит от количества "единиц роутинга"...
Если их с десяток - то и париться особо не о чем. А вот если такое измеряется сотнями - тогда волей, не волей, а придется придумывать некую унификацию УРЛов, дабы у них была какая-то общая идея.

Elfix, прикинь сколько этого будет у тебя... Разложи на "кучки"...
Тогда тут смогут что-то посоветовать по решению.

[Rise]

Сделал несколько API

"текущего пользователя" это лишнее, один из принципов архитектуры REST это stateless.