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

Question

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

Например:

api.service.com/helloWorld/userId/x 

или

api.service.com/hello_world/user_id/x 

Примечание: Это не вопрос RESTful дизайна API, а руководящие принципы именования конвенции использовать для возможных компонентов пути и/или запроса используемые строки.

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

Answer 1

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

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

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

Answer 2

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

api.service.com/helloWorld/userId/x

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

Answer 3

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

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

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

Answer 4

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

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

Answer 5

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

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

Answer 6

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

Answer 7

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

Answer 8

«UserId» - это совершенно неправильный подход. Подходы Verb (HTTP Methods) и Noun - это то, что Roy Fielding предназначено для The REST architecture. Существительных либо:

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, even html.

можно выделить коллекцию, добавляя «S» в конце, как:

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

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

Answer 9

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

Answer 10

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

• CLIENT_ID
• client_secret

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

См: https://tools.ietf.org/html/rfc6749