Существуют ли правила конвенции об именах для API REST?

Ответ 1

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

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

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

Ответ 2

Посмотрите на 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/.

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

Ответ 3

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

Ответ 4

"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-адрес менее дружелюбен к ним.

Ответ 5

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

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

Ответ 6

Доменные имена не чувствительны к регистру, но остальная часть URI, безусловно, может быть. Это большая ошибка, предполагающая, что URI не чувствительны к регистру.

Ответ 7

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

Ответ 8

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

api.service.com/helloWorld/userId/x

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

Ответ 9

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

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

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

Ответ 10

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

• client_id
• client_secret

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

Смотрите: https://tools.ietf.org/html/rfc6749