Czy istnieją jakieś wytyczne dotyczące konwencji nazewnictwa dla interfejsów API REST? [Zamknięte]

Czy podczas tworzenia interfejsów API REST istnieją jakieś wytyczne lub standardy defacto dotyczące konwencji nazewnictwa w interfejsie API (np .: komponenty ścieżki punktu końcowego adresu URL, parametry kwerendy)? Czy czapki wielbłądów są normą, czy podkreślają? inni?

Na przykład:

api.service.com/helloWorld/userId/x

lub

api.service.com/hello_world/user_id/x

Uwaga: Nie jest to kwestia projektu interfejsu API RESTful, lecz wytyczne konwencji nazewnictwa, które należy stosować w przypadku ewentualnych komponentów ścieżki i / lub parametrów ciągu zapytania.

Wszelkie wytyczne będą mile widziane.

Myślę, że powinieneś unikać czapek wielbłądów. Normą jest stosowanie małych liter. Unikałbym również podkreśleń i zamiast tego używałbym myślników

Twój adres URL powinien więc wyglądać tak (ignorując problemy projektowe, o które prosiłeś :-))

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

Interfejs API REST dla Dropbox , Twitter , Google Web Services i Facebook używa podkreślników.

Przyjrzyj się uważnie identyfikatorom URI zwykłych zasobów internetowych. To są twój szablon. Pomyśl o drzewach katalogów; używaj prostych, podobnych do Linuksa nazw plików i katalogów.

HelloWorldnie jest naprawdę dobrą klasą zasobów. To nie wydaje się być „rzeczą”. Być może, ale nie jest bardzo rzeczownikowy. ZAgreeting jest rzeczą.

user-idmoże być rzeczownik, który pobierasz. Wątpliwe jest jednak, aby wynik twojego żądania był tylko identyfikatorem użytkownika. O wiele bardziej prawdopodobne jest, że wynikiem żądania jest Użytkownik. Dlatego userjest rzeczownik, który pobierasz

www.example.com/greeting/user/x/

Dla mnie to ma sens. Skoncentruj się na tym, aby żądanie REST było rodzajem wyrażenia rzeczownikowego - ścieżki w hierarchii (lub taksonomii lub katalogu). Używaj najprostszych rzeczowników, jeśli to możliwe, unikając wyrażeń rzeczownikowych.

Ogólnie rzecz biorąc, złożone wyrażenia rzeczownikowe zwykle oznaczają kolejny krok w hierarchii. Więc nie masz /hello-world/user/i /hello-universe/user/. Masz /hello/world/user/i hello/universe/user/. Lub ewentualnie /world/hello/user/i/universe/hello/user/ .

Chodzi o to, aby zapewnić ścieżkę nawigacji między zasobami.

„UserId” jest całkowicie niewłaściwym podejściem. Czasownik (metody HTTP) i rzeczownik są tym, co Roy Fielding miał na myśli dla architektury REST . Rzeczowniki to:

1. Collection rzeczy
2. rzecz

Jedną dobrą konwencją nazewnictwa jest:

[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

Gdzie {media_type} jest jednym z: json, xml, rss, pdf, png, a nawet html.

Można wyróżnić kolekcję, dodając „s” na końcu, na przykład:

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

Ale to oznacza, że ​​musisz śledzić, gdzie umieściłeś „s”, a gdzie nie. Dodatkowo połowa planety (Azjaci na początek) mówi językami bez wyraźnej liczby mnogiej, więc adres URL jest dla nich mniej przyjazny.

Nie. REST nie ma nic wspólnego z konwencjami nazewnictwa URI. Jeśli uwzględnisz te konwencje jako część interfejsu API poza pasmem, a nie tylko za pomocą hipertekstu, wówczas interfejs API nie będzie RESTful.

Aby uzyskać więcej informacji, zobacz http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

W nazwach domen nie jest rozróżniana wielkość liter, ale reszta identyfikatora URI z pewnością może być. Wielkim błędem jest założenie, że identyfikatory URI nie uwzględniają wielkości liter.

Mam listę wskazówek na http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html, które wykorzystaliśmy w prod. Wytyczne są zawsze dyskusyjne ... Myślę, że konsekwencja jest czasem ważniejsza niż doprowadzenie rzeczy do perfekcji (jeśli coś takiego istnieje).

Nie sądzę, że sprawa wielbłąda jest problemem w tym przykładzie, ale wyobrażam sobie bardziej RESTfulową konwencję nazewnictwa dla powyższego przykładu:

api.service.com/helloWorld/userId/x

zamiast uczynić userId parametrem zapytania (co jest całkowicie legalne), mój przykład oznacza ten zasób w IMO w sposób bardziej RESTful.

Jeśli uwierzytelniasz swoich klientów za pomocą Oauth2, myślę, że będziesz potrzebować podkreślenia dla co najmniej dwóch nazw parametrów:

• Identyfikator klienta
• Client_secret

Użyłem camelCase w moim (jeszcze nieopublikowanym) interfejsie API REST. Pisząc dokumentację API, myślałem o zmianie wszystkiego na snake_case, więc nie muszę wyjaśniać, dlaczego parametry Oauth są snake_case, a inne parametry nie.

Zobacz: https://tools.ietf.org/html/rfc6749

Powiedziałbym, że lepiej jest używać jak najmniej znaków specjalnych w adresach URL REST. Jedną z zalet REST jest to, że sprawia, że ​​„interfejs” usługi jest łatwy do odczytania. Sprawa wielbłąda lub sprawa Pascala jest prawdopodobnie dobra dla nazw zasobów (Użytkownicy lub użytkownicy). Nie wydaje mi się, żeby wokół REST istniały twarde standardy.

Myślę też, że Gandalf ma rację, zwykle w REST jest czystsze, aby nie używać parametrów ciągu zapytania, ale zamiast tego tworzyć ścieżki, które określają zasoby, z którymi chcesz się zajmować.

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