Wygląd adresów URL nie ma nic wspólnego z usługą REST. Wszystko idzie. W rzeczywistości jest to „szczegół implementacji”. Więc tak jak nazywasz swoje zmienne. Muszą być jedyne w swoim rodzaju i trwałe.
Nie marnuj na to zbyt wiele czasu, po prostu dokonaj wyboru i trzymaj się go / bądź konsekwentny. Na przykład, jeśli korzystasz z hierarchii, robisz to dla wszystkich swoich zasobów. Jeśli korzystasz z parametrów zapytań ... itd., Podobnie jak konwencje nazewnictwa w kodzie.
Dlaczego tak ? O ile mi wiadomo, API „RESTful” ma być możliwe do przeglądania (wiesz… „Hypermedia jako silnik stanu aplikacji”), dlatego klient API nie dba o to, jakie są twoje adresy URL, o ile są ważne (nie ma SEO, żaden człowiek nie musiałby czytać tych „przyjaznych adresów URL”, z wyjątkiem tego, że może służyć do debugowania ...)
To, jak ładny / zrozumiały jest adres URL w interfejsie API REST, jest interesujące tylko dla programisty interfejsu API, a nie dla klienta interfejsu API, tak jak nazwa zmiennej w kodzie.
Najważniejsze jest to, że klient interfejsu API wie, jak interpretować typ multimediów. Na przykład wie, że:
- Twój typ multimediów ma właściwość links, która zawiera listę dostępnych / powiązanych linków.
- Każdy link jest identyfikowany przez relację (tak jak przeglądarki wiedzą, że link [rel = "arkusz stylów"] oznacza, że jego arkusz stylów lub rel = favico jest linkiem do favicon ...)
- i wie, co oznaczają te relacje („firmy” oznaczają listę firm, „wyszukiwanie” oznacza szablonowy adres URL do wyszukiwania na liście zasobów, „działy” oznaczają działy bieżącego zasobu)
Poniżej znajduje się przykładowa wymiana HTTP (ciała są w yaml, ponieważ łatwiej jest pisać):
Żądanie
GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml
Odpowiedź: lista linków do głównego zasobu (firmy, ludzie, cokolwiek ...)
HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:04:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml
# body: this is your API's entrypoint (like a homepage)
links:
# could be some random path https://api.acme.local/modskmklmkdsml
# the only thing the API client cares about is the key (or rel) "companies"
companies: https://api.acme.local/companies
people: https://api.acme.local/people
Żądanie: link do firm (przy użyciu body.links.companies poprzedniej odpowiedzi)
GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml
Odpowiedź: częściowa lista firm (poniżej pozycji), zasób zawiera powiązane linki, takie jak link do uzyskania następnych kilku firm (body.links.next) inny (szablonowy) link do wyszukiwania (body.links.search)
HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:06:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml
# body: representation of a list of companies
links:
# link to the next page
next: https://api.acme.local/companies?page=2
# templated link for search
search: https://api.acme.local/companies?query={query}
# you could provide available actions related to this resource
actions:
add:
href: https://api.acme.local/companies
method: POST
items:
- name: company1
links:
self: https://api.acme.local/companies/8er13eo
# and here is the link to departments
# again the client only cares about the key department
department: https://api.acme.local/companies/8er13eo/departments
- name: company2
links:
self: https://api.acme.local/companies/9r13d4l
# or could be in some other location !
department: https://api2.acme.local/departments?company=8er13eo
Tak więc, jak widzisz, jeśli korzystasz z linków / relacji, sposób, w jaki tworzysz ścieżkę, część twoich adresów URL nie ma żadnej wartości dla twojego klienta API. A jeśli komunikujesz strukturę swoich adresów URL swojemu klientowi jako dokumentację, to nie robisz REST (lub przynajmniej nie Poziom 3 zgodnie z „ modelem dojrzałości Richardsona ”)