Существуют ли какие-либо рекомендации по соглашению об именах для API REST? [закрытый]

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

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

HelloWorld не очень хороший класс ресурсов. Это не похоже на"вещь". Это может быть, но это не очень похоже на существительное. А greeting - это вещь.

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) и существительное подход-это то, что Рой Филдинг предназначена для остальная архитектура. Существительные либо:

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

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

[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*

но это означает, что вы должны отслеживать, где вы поставили '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. Руководящие принципы всегда спорны... Я думаю, что последовательность иногда более важна, чем получение вещей совершенными (если есть такая вещь).

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

api.service.com/helloWorld/userId/x

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

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

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

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

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

• client_id
• client_secret

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

посмотреть: https://tools.ietf.org/html/rfc6749