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

212

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.

jnorris
źródło

Odpowiedzi:

150

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
LiorH
źródło
187
Zgodnie z RFC2616 tylko schemat i części hosta w adresie URL nie rozróżniają wielkości liter. W pozostałej części adresu URL, tj. Ścieżce i zapytaniu, MUSI być rozróżniana wielkość liter. w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.3
Darrel Miller
10
Daniel, masz rację, dzięki za zwrócenie na to uwagi. Jednak de facto zwykle oczekujemy, że adresy URL będą ignorować przypadki, szczególnie część nazwy zasobu. Nie ma sensu, aby identyfikator użytkownika i identyfikator użytkownika zachowywały się inaczej (chyba że jeden z nich zwróci 404)
LiorH
18
@LiorH: Jak myślisz, dlaczego rozróżnianie wielkości liter ma „bez sensu”? W wielu innych kontekstach rozróżniana jest wielkość liter, aby uzyskać dobry efekt. Istnieje kilka usług internetowych (np. Amazon S3), które wymuszają rozróżnianie wielkości liter w punktach końcowych adresów URL i myślę, że to całkiem właściwe.
Hank
6
@Dennis Systemy plików serwera Windows domyślnie nie uwzględniają wielkości liter, chyba że bardzo się mylę. Technet.microsoft.com/en-us/library/cc725747.aspx
samspot
5
@samspot Dobry! Myślałem, że podczas tworzenia serwerów Windows od razu rozróżniał wielkie i małe litery. WOW, wciąż przepychali ICH tak długo, jak mogli, tj. „1 MicroSoft Way”. ;-)
Dennis
87

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

jz1108
źródło
24
Jednym z efektów ubocznych jest to, że podkreślone „słowa” są utrzymywane w całości, razem w indeksach wyszukiwania Google. Te hybrydowe są podzielone na osobne słowa.
Dennis
Przykład: dev.twitter.com/docs/api/1.1
mike kozelsky
11
Chociaż interfejs API Map Google korzysta z podkreślników, Przewodnik po stylu Google wymaga etui Camel Case. Google+ API i Custom Search API , między innymi, należy Camel Case.
Benjamin
2
Jednak nadal używają „-” jako separatora tych adresów URL: P developers.google.com/custom-search/json-api/v1/reference/cse/… developers.google.com/+/best-practices dev.twitter. com / Overview / Case-Studies Z drugiej strony używają camelCase w parametrach zapytania.
Mattias
1
Nikt nie wie ...
Piotr Kula
84

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.

S.Lott
źródło
4
Moje pytanie dotyczy bardziej konwencji nazewnictwa ostatecznych nazw ścieżek i / lub parametrów zapytania, niezależnie od tego, jakie mogą być. Zgadzam się z zaleceniami projektowymi, więc dziękuję, ale w tym pytaniu pytam tylko o konwencje nazewnictwa.
jnorris
1
Należy zauważyć, że nic nie stoi na przeszkodzie, aby używać REST dla zasobów niehierarchicznych. Rzeczywiste konwencje nazewnictwa URI, których używasz, są nieistotne, po prostu używaj tego, co według ciebie wygląda ładnie i jest łatwe do przetworzenia na serwerze. Klient nie powinien wiedzieć nic o generowaniu identyfikatorów URI, ponieważ w odpowiedziach należy wysłać identyfikatory URI do zasobów za pośrednictwem hipertekstu.
aehlke,
30

„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.

Dennis
źródło
Co należy rozumieć przez {var}? Jeśli szukam użytkownika według nazwy, która byłaby na przykład ... / user / username / tomsawyer?
Hans-Peter Störr
1
Gdybyś miał trzy zmienne (var) o nazwie x, y, z, wtedy twój URL wyglądałby następująco: sub.domain.tld / x / value_of_x / y / value_of_y / z / value_of_z
Dennis
@ hstoerr Dla pewności, że większość języków skryptowych używa „podstawiania zmiennych nawiasów klamrowych”. Zatem {var} oznacza, że ​​znajduje się tam jakaś zmienna (jej nazwa), a więc następująca {wartość} jest tam, gdzie wartość {var} przed nią. Przykład: sub.domain.tld / script / {var} / {value} .json [www.yelp.com/food_reviews/review_averages_higher_than/4.json] będzie próbował uzyskać wyniki json z yelp.com dla pokazów jedzenia wartość wyższa niż 4.
Dennis
To moim zdaniem najlepsza odpowiedź i uznanie dla myślenia międzynarodowego.
beiller
14

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

aehlke
źródło
44
Daj spokój ... nadal fajnie jest mieć ładnie wyglądające adresy URL.
HDave
1
Zgadzam się z @HDave, bardzo w duchu REST są adresy URL, które można łatwo zrozumieć. Pracujesz z adresami URL, dlaczego nie chcesz, aby były tak łatwe do zrozumienia, jak nazwy zmiennych i parametrów w kodzie?
mahemoff,
4
@ mahemoff przepraszam, to jestem super pedantyczny. Ale to, jak wyglądają Twoje adresy URL, nie ma nic wspólnego z REST. To nie znaczy, że nie są to dobre rzeczy, są po prostu prostopadłe do tego, co opisuje REST. Mylące jest twierdzenie, że REST polega na strukturze adresów URL w ten sposób, ponieważ prowadzi to do osób opisujących interfejsy RPC API jako REST tylko dlatego, że mają czytelne / ustrukturyzowane adresy URL.
aehlke,
5
Podsumowując, ładnie wyglądające adresy URL są świetne i każdy powinien je mieć. Nie ma to jednak nic wspólnego z REST.
aehlke,
1
@aehlke dziękuję za wyjaśnienie tego. Reszta nie dotyczy struktur adresów URL. Nie rozumiem, dlaczego tak trudno ludziom zrozumieć.
user1431072,
9

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.


źródło
2

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.

Gandalf
źródło
Nie jest to kwestia projektu interfejsu API RESTful, a raczej wytycznych konwencji nazewnictwa, które należy zastosować w przypadku ewentualnych użytych komponentów ścieżki i / lub parametrów ciągu zapytania. W twoim przykładzie, czy komponenty ścieżki powinny być w wielbłądach, tak jak już używałeś, czy podkreśla?
jnorris
Cóż, ponieważ w REST twoje adresy URL są twoimi interfejsami, jest to rodzaj pytania API. Chociaż nie sądzę, aby istniały jakieś wytyczne dotyczące twojego przykładu, osobiście wybrałbym etui na wielbłądy.
Gandalf
Nie należy używać parametrów zapytania dla zasobów, które mają być buforowane na dowolnym poziomie stosu HTTP.
aehlke,
@aehlke Dokładnie odwrotnie. Jeśli NIE chcesz buforować parametrów zapytania, użyj stylu GET dla parametrów, ~ LUB ~ upewnij się, że DARN SURE zmodyfikuje / wstawi nagłówki anty buforujące dla wszystkiego, czego nie chcesz buforować. Jest też nagłówek, który jest skrótem returend obiektu / strony, użyj go, aby wskazać zmiany rzeczy, które chcesz buforować, ale zaktualizowane, gdy zostaną wprowadzone zmiany.
Dennis
@aehlke Dowiedziałem się o buforowaniu i dodaję go. Pamiętam prezentację CodeCamp, w której jedno ze przyspieszeń wykonywało wszystkie te nagłówki, a następnie zmieniłem nazwę pliku i wszystkie odniesienia do niego, gdy zmieniła się jego zawartość, aby uzyskać od przeglądarek i serwerów proxy nową wersję serwera po długim czasie buforowania zestaw. Oto wszystkie krwawe szczegóły: developers.google.com/speed/docs/best-practices/caching
Dennis
2

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

Michael
źródło
0

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

Andy White
źródło