Лучшие практики отдыха: какому стандарту я должен следовать?

Question

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

https://www.restapitutorial.com/resources.html Книга REST-API-Design-Rulebook от другого вопроса блога и stackoverflow.

Например, чтобы получить информацию о сотруднике сидентификатор, который мы используем uri, как показано ниже

http://myapp-name.myorganization.com/employees/employeeid/123456

Но все вышеперечисленные ресурсы говорят мне сделать это следующим образом

http://myapp-name.myorganization.com/employees/123456

Точно так же, если я хочу пойти получить информацию о сотруднике с идентификатором 12345,мой URI, как показано ниже

http://myapp-name.myorganization.com/countries/country/US/employeeid/12345

, в отличие от

http://myapp-name.myorganization.com/countries/US/12345

Значит ли это, что мой URI не является стандартным?

Answer 1

Это мой URI не является стандартным?

Нет, ваш URI в порядке.REST не заботится о том, какое правописание вы используете для своих идентификаторов, если они соответствуют RFC 3986 .Существует также RFC 7320 , в котором описываются «Лучшие практики», но вы, вероятно, обнаружите, что эти лучшие практики все еще оставляют вам большую свободу.

Подумайте «имена переменных» - различныесообщества будут иметь свои собственные соглашения о том, как следует называть имена переменных, но нет никакого стандарта.

То же самое относится к идентификаторам в REST - это непрозрачные строки, которые на самом деле ни потребитель API, ни клиентнадо разобрать.(Пример: когда вы в последний раз просматривали URI, используемый при отправке запроса в Google?)

Некоторые инфраструктуры маршрутизации будет проще в использовании, если вы придерживаетесь определенного соглашения, но это просто реализацияподробности на сервере, клиенту все равно.

Answer 2

Это всего лишь рекомендации.Вы не можете охватить все виды возможностей вашего бизнеса и потребностей в документации по отдыху.

Говоря о ваших примерах,

http://myapp-name.myorganization.com/employees/employeeid/123456

И

http://myapp-name.myorganization.com/employees/123456

Оба верны.Но может быть лучше (короче).

Обычно я предпочитаю второй и использую первый для альтернатив .Например, если я хочу найти сотрудника по идентификатору (метод «поиска по умолчанию» для поиска сотрудников) или по его уникальному внутреннему балансовой единице, я предпочитаю использовать соответственно:

/employees/123456         # by id
/employees/code/A899123A  # by code

Аналогично, еслиЯ хочу пойти получить информацию о сотруднике с идентификатором 12345, мой URI, как показано ниже http://myapp -name.myorganization.com / страны / страна / США / employeeid / 12345

Этот URL-адрес означает для меня, что вы пытаетесь найти сотрудника с идентификатором 12345 в стране США.Но может быть и короче, если для поиска стран в вашем API используется термин US:

 /countries/US/employees/12345

вместо http://myapp -name.myorganization.com /стран / США / 12345

Этот кажется запутанным.Вы пытаетесь найти то, что с идентификатором 12345?Трудно ответить только в поисках URL.Таким образом, /countries/US/employees/12345 является более последовательным.

Если идея состоит в том, чтобы найти сотрудника в какой-либо стране с некоторым кодом, URL-адрес может следовать той же схеме: /countries/US/employees/code/A899123A