При создании API REST существуют ли какие-либо рекомендации или стандарты defacto для соглашений об именах в 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
API REST для Dropbox, Twitter, Google Web Services и Facebook все использует подчеркивания.
Посмотрите на URI для обычных веб-ресурсов. Это ваш шаблон. Подумайте о деревьях каталогов; используйте простые имена файлов и каталогов, похожие на Linux.
HelloWorld
не очень хороший класс ресурсов. Кажется, это не "вещь". Это может быть, но это не очень похоже на существительное. A 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" - это совершенно неправильный подход. Метод Verb (HTTP Method) и Noun - это Roy Fielding, предназначенный для Архитектура REST. Существительные:
Одно хорошее соглашение об именах:
[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, even html.
Можно выделить коллекцию, добавив в конце 's', например:
'users.json' *collection of things*
'user/id_value.json' *single thing*
Но это означает, что вам нужно отслеживать, где вы положили 's', а где нет. Плюс половина планеты (азиаты для стартеров) говорит на языках без явного множественного числа, поэтому 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 параметром запроса (который является совершенно законным), мой пример означает, что ресурс in, IMO, более RESTful.
Я бы сказал, что предпочтительнее использовать как можно меньше специальных символов в URL-адресах REST. Одним из преимуществ REST является то, что он упрощает чтение "интерфейса" для услуги. Случай Верблюда или Паскаль, вероятно, хорош для имен ресурсов (пользователей или пользователей). Я не думаю, что в REST есть какие-то жесткие стандарты.
Кроме того, я думаю, что Gandalf прав, он обычно чист в REST, чтобы не использовать параметры строки запроса, а вместо этого создавать пути, определяющие, с какими ресурсами вы хотите иметь дело.
Если вы аутентифицируете своих клиентов с помощью Oauth2, я думаю, вам понадобится подчеркнуть хотя бы два имени вашего параметра:
Я использовал camelCase в моем (еще не опубликованном) REST API. При написании документации API я думал об изменении всего на snake_case, поэтому мне не нужно объяснять, почему параметры Oauth являются snake_case, а другие параметры - нет.
Смотрите: https://tools.ietf.org/html/rfc6749