Существуют ли правила именования для REST API? [закрыто]

При создании REST API существуют ли какие-либо руководящие принципы или стандарты по умолчанию для соглашений об именах в API (например: компоненты пути конечной точки URL, параметры строки запроса)? Шапки верблюда - норма или подчеркивание? другие?

Например:

api.service.com/helloWorld/userId/x

или

api.service.com/hello_world/user_id/x

Примечание. Речь идет не о разработке API RESTful, а о правилах соглашения об именах, которые следует использовать для возможных компонентов пути и / или используемых параметров строки запроса.

Любые рекомендации будут оценены.

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

Таким образом, ваш URL должен выглядеть следующим образом (игнорируя проблемы дизайна, как вы просили :-))

api.service.com/hello-world/user-id/x

REST API для Dropbox , Twitter , Google Web Services и Facebook использует подчеркивания.

Посмотрите внимательно на URI для обычных веб-ресурсов. Это ваш шаблон. Подумайте о деревьях каталогов; используйте простые Linux-подобные имена файлов и каталогов.

HelloWorldне очень хороший класс ресурсов. Это не похоже на «вещь». Возможно, но это не очень похоже на существительное. А greetingэто вещь.

user-idможет быть существительным, которое вы выбираете. Однако сомнительно, что результатом вашего запроса является только user_id. Гораздо более вероятно, что результатом запроса является пользователь. Следовательно, userэто существительное, которое вы выбираете?

www.example.com/greeting/user/x/

Имеет смысл для меня. Сосредоточьтесь на том, чтобы сделать ваш запрос REST своего рода существительной фразой - путем через иерархию (или таксономию, или каталог). Используйте самые простые из возможных существительных, избегая по возможности фраз с существительными.

Обычно сложные составные фразы обычно означают еще один шаг в вашей иерархии. Так что у вас нет /hello-world/user/и /hello-universe/user/. У вас есть /hello/world/user/и hello/universe/user/. Или возможно /world/hello/user/и/universe/hello/user/ .

Дело в том, чтобы обеспечить навигационный путь среди ресурсов.

UserId - совершенно неправильный подход. Подход глагола (HTTP-методы) и существительного - вот что Рой Филдинг имел в виду для архитектуры REST . Существительными являются либо:

1. Коллекция вещей
2. вещь

Одно хорошее соглашение об именах:

[POST or Create](To the *collection*)
sub.domain.tld/class_name.{media_type} 

[GET or Read](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[PUT or Update](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[DELETE](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[GET or Search](of a *collection*, FRIENDLY URL)
sub.domain.tld/class_name.{media_type}/{var}/{value}/{more-var-value-pairs}

[GET or Search](of a *collection*, Normal URL)
sub.domain.tld/class_name.{media_type}?var=value&more-var-value-pairs

Где {media_type} является одним из: json, xml, rss, pdf, png, даже html.

Можно выделить коллекцию, добавив в конце 's', например:

'users.json' *collection of things*
'user/id_value.json' *single thing*

Но это означает, что вы должны отслеживать, где вы положили «а», а где нет. Плюс половина планеты (азиаты для начинающих) говорит на языках без явного множественного числа, поэтому URL-адрес для них менее дружественный.

Нет. REST не имеет ничего общего с соглашениями об именах URI. Если вы включите эти соглашения как часть своего API, внеполосного, а не только через гипертекст, то ваш API не является RESTful.

Для получения дополнительной информации см. Http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven.

Доменные имена не чувствительны к регистру, но остальная часть URI, безусловно, может быть. Большая ошибка - считать, что URI не чувствительны к регистру.

У меня есть список рекомендаций по адресу http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html, который мы использовали в prod. Руководящие принципы всегда спорны ... Я думаю, что последовательность иногда важнее, чем доводить дело до совершенства (если оно есть).

Я не думаю, что случай верблюда является проблемой в этом примере, но я предполагаю, что более RESTful соглашение об именах для приведенного выше примера будет:

api.service.com/helloWorld/userId/x

вместо того, чтобы делать userId параметром запроса (что совершенно законно), мой пример обозначает этот ресурс, IMO, более RESTful.

Если вы аутентифицируете своих клиентов с помощью Oauth2, я думаю, вам понадобится подчеркнуть как минимум два из ваших имен параметров:

• ID клиента
• client_secret

Я использовал camelCase в моем (еще не опубликованном) REST API. При написании документации по API я думал о том, чтобы изменить все на snake_case, поэтому мне не нужно объяснять, почему параметры Oauth - это snake_case, а другие - нет.

Видеть: https://tools.ietf.org/html/rfc6749

Я бы сказал, что в URL REST желательно использовать как можно меньше специальных символов. Одним из преимуществ REST является то, что он делает «интерфейс» службы легким для чтения. Случай с верблюдом или случай с Паскалем, вероятно, подходит для имен ресурсов (пользователей или пользователей). Я не думаю, что действительно существуют какие-то жесткие стандарты в отношении REST.

Кроме того, я думаю, что Гэндальф прав: в REST обычно проще не использовать параметры строки запроса, а вместо этого создавать пути, определяющие, с какими ресурсами вы хотите иметь дело.

http://api.example.com/HelloWorld/Users/12345/Order/3/etc