Как следует подходить к именованию API в микросервисной архитектуре?

Question

[Ваня Петило]

Работаю над платформой с микросервисной архитектурой. В наличии микросервисы и API-шлюз.
Хочу немного привести в порядок все наименования (эндпоинты, пути и т.д.).
Есть ли какие-то best-practices по этому поводу?
К примеру, если взять микросервис для работы с юзерами, следует ли мне прописывать в начале эндоинтов /user/v1?
Или же мне стоит вписать /user в качестве корневого uri для API в шлюзе, а в самом микросервисе прописывать только версионирование?

Comments

[Сергей Горностаев]

/v1/user, а то по правилам REST получается, что у вас есть user с идентификатором v1.

[Slonoed]

Сергей Горностаев, по правилам REST будет /v1/user/:userid

[Сергей Горностаев]

Slonoed, смотря к какому ресурсу обращаетесь.

Answer 1

[mayton2019]

Надо описать в документации все методы и endpoins. Лучше в открытом формате типа Swagger/OpenAPI. И показать их заинтересованным лицам. Тем кто будет этот API использовать. Вот если у них не будет вопросов - значит все понятно и хорошо. Если они будут говорить WTF - то надо все эти вотафаки аккуратно записать и исправить.

Answer 2

[Slonoed]

Если у вас ТОЧНО будет версионирование, тогда /v1/user
Но версию можно передавать и в http headers, если клиент в состоянии это сделать, то так даже визуально проще.
Определите, какой вариант вам проще реализовать, например:
/контроллер/действие/:id
или
/контроллер/:id/действие

Answer 3

[Владимир Коротенко]

плевать. главное оставляйте документацию на все версии.