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


212

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

Например:

api.service.com/helloWorld/userId/x

или

api.service.com/hello_world/user_id/x

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

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

Ответы:


150

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

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

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

187
Согласно RFC2616, только схема и части хоста URL не чувствительны к регистру. Остальная часть URL, т.е. путь и запрос, ДОЛЖНЫ быть чувствительными к регистру. w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.3
Даррел Миллер

10
Даниэль, ты прав, спасибо, что указал на это. Однако де-факто мы обычно ожидаем, что URL игнорируют регистры, особенно часть имени ресурса. Для userid & UserId не имело бы смысла вести себя по-разному (если только один из них не возвращает 404)
LiorH

18
@LiorH: почему вы думаете, что «бессмысленно» учитывать регистр? Множество других контекстов чувствительны к регистру для хорошего эффекта. Есть некоторые веб - сервисы (например , Amazon S3) , которые делают исполнение чувствительность к регистру для URL - адресов конечных точек, и я думаю , что это вполне уместно.
Хэнк

6
@Dennis Windows серверные файловые системы по умолчанию нечувствительны к регистру, если только я не ошибаюсь technet.microsoft.com/en-us/library/cc725747.aspx
samspot

5
@ samspot Хороший! Я думал, что Windows сразу указали имена файлов с учетом регистра при создании серверов. ВАУ, они все еще продвигали свой путь так долго, как могли, то есть «1 MicroSoft Way». ;-)
Деннис

87

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


24
Одним из побочных эффектов этого является то, что подчеркнутые «слова» хранятся вместе в поисковых индексах Google. Переносимые слова разбиты на отдельные слова.
Деннис


11
В то время как API Карт Google использует подчеркивания, Руководство по стилю Google требует использования Camel Case. Google+ API и Custom Search API , в частности, использовать Camel Case.
Бенджамин

2
Тем не менее, они все еще используют «-» в качестве разделителя этих URL: P developers.google.com/custom-search/json-api/v1/reference/cse/… developers.google.com/+/best-practices dev.twitter. com / Overview / case-study С другой стороны, они используют camelCase в параметрах запроса.
Маттиас

1
Никто не знает ...
Петр Кула

84

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

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


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

1
Просто заметьте, что ничто не мешает вам использовать REST для неиерархических ресурсов. Фактические соглашения об именах URI, которые вы используете, несущественны, просто используйте то, что, по вашему мнению, выглядит хорошо и вам легко разобрать на сервере. Клиент не должен ничего знать о генерации ваших URI, так как вам нужно отправлять URI ресурсам через гипертекст в ваших ответах.
aehlke

30

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-адрес для них менее дружественный.


Что подразумевается под {var}? Если я буду искать пользователя по имени, это будет, например, ... / user / username / tomsawyer?
Ганс-Петер Стёрр

1
Если бы у вас было три переменные (var) с именами x, y, z, то ваш URL был бы похож на: sub.domain.tld / x / value_of_x / y / value_of_y / z / value_of_z
Деннис

@hstoerr Просто чтобы быть уверенным, что я ясен, большинство языков сценариев используют своего рода «подстановку переменных в фигурных скобках». Таким образом, {var} означает, что там находится некоторая переменная (ее имя), и поэтому следующее {value} - это то, где находится значение {var} перед ним. Пример: sub.domain.tld / script / {var} / {value} .json [www.yelp.com/food_reviews/review_averages_higher_than/4.json] будет пытаться получить результаты json с сайта yelp.com для показов продуктов питания, показывающих значение выше 4.
Деннис

Это лучший ответ, на мой взгляд, и похвала за международное мышление.
beiller

14

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

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


44
Отдохни ... все равно приятно иметь красивые URL.
HDave

1
Согласитесь с @HDave, в духе REST очень важно иметь URL-адреса, которые легко понять. Вы работаете с URL-адресами, почему вы не хотите, чтобы они были так же легко понятны, как имена переменных и параметров в вашем коде?
mahemoff

4
@mahemoff извините, это я супер педантичный. Но то, как выглядят ваши URL, не имеет ничего общего с REST. Это не значит, что они не очень хорошие вещи, они просто ортогональны тому, что описывает REST. Вводить в заблуждение тот факт, что REST подразумевает структурирование URL-адресов таким образом, поскольку это приводит к тому, что люди описывают API-интерфейсы RPC как REST только потому, что они имеют читаемые / структурированные URL-адреса.
aehlke

5
В общем, красивые URL-адреса - это здорово, и каждый должен иметь их. Это не имеет ничего общего с REST, хотя.
aehlke

1
@aehlke спасибо за разъяснение. Отдых не о структурах URL. Я не понимаю, почему людям так трудно понять.
user1431072

9

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


6

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


2

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

api.service.com/helloWorld/userId/x

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


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

Ну, поскольку в REST ваши URL-адреса являются вашими интерфейсами, то это вопрос API. Хотя я не думаю, что есть какие-либо рекомендации, характерные для вашего примера, я бы остановился на случае с верблюдом.
Гэндальф,

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

@aehlke Также верно и обратное. Если вы НЕ хотите, чтобы параметры запроса кэшировались, используйте стиль GET для параметров, ~ ИЛИ ~ заставьте DARN SURE изменить / вставить заголовки анти-кэширования для всего, что вы не хотите кэшировать. Кроме того, есть заголовок, который является хешем объекта / страницы, который используется для повторного использования. Используйте его, чтобы указать изменения вещей, которые вы хотите кэшировать, но которые обновляются при внесении изменений.
Деннис

@aehlke Узнал о кешировании и добавляю его. Я помню презентацию CodeCamp, в которой одно из ускорений делало все эти заголовки, а затем меняло имя файла и все ссылки на него, когда его содержимое изменялось, чтобы заставить браузеров и прокси-серверы отправлять на сервер более новую версию после долгого времени кеширования. устанавливать. Вот все ужасные подробности: developers.google.com/speed/docs/best-practices/caching
Деннис,

2

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

  • ID клиента
  • client_secret

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

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


0

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

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

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

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.