Чи існують якісь рекомендації щодо встановлення імен для API REST? [зачинено]

Чи створюються API REST, чи існують якісь вказівки чи стандартні стандарти для іменувань конвенцій в 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 та 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" - це зовсім неправильний підхід. Вербовий (методи 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 менш привітний для них.

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

Я не думаю, що справа у верблюдах не є проблемою у цьому прикладі, але я уявляю, що більш РЕЗЕКЦІЙНА конвенція про іменування для вищевказаного прикладу була б:

api.service.com/helloWorld/userId/x

замість того, щоб зробити userId параметром запиту (що цілком законно), мій приклад позначає цей ресурс в IMO, більш РЕСТЕВНІЙ спосіб.

Якщо ви автентифікуєте своїх клієнтів за допомогою Oauth2, я думаю, вам знадобиться підкреслити принаймні два ваших імені параметрів:

• client_id
• client_secret

Я використовував camelCase у своєму (ще не опублікованому) API REST. Під час написання документації API я думав змінити все на snake_case, тому мені не доведеться пояснювати, чому парами Oauth є snake_case, а інші парами - ні.

Дивіться: https://tools.ietf.org/html/rfc6749

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

Крім того, я думаю, що Гандальф має рацію, зазвичай в REST зазвичай чистіше не використовувати параметри рядка запиту, а натомість створювати шляхи, які визначають, з якими ресурсами ви хочете мати справу.

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