То, как выглядят ваши URL, не имеет ничего общего с REST. Все идет. На самом деле это «деталь реализации». Так же, как вы называете свои переменные. Все они должны быть уникальными и долговечными.
Не тратьте слишком много времени на это, просто сделайте выбор и придерживайтесь его / будьте последовательны. Например, если вы используете иерархию, вы делаете это для всех своих ресурсов. Если вы идете с параметрами запроса ... и т. Д., Так же, как соглашения о присвоении имен в вашем коде.
Почему так ? Насколько я знаю, API "RESTful" должен быть доступен для просмотра (вы знаете ... "Гипермедиа как движок состояния приложения"), поэтому клиент API не заботится о том, на что похожи ваши URL, пока они действительный (нет SEO, нет человека, который должен читать эти "дружеские ссылки", кроме как для отладки ...)
То, насколько приятный / понятный URL-адрес в REST API, интересует вас, как разработчика API, а не клиента API, как было бы имя переменной в вашем коде.
Самое главное, чтобы ваш клиент API знал, как интерпретировать ваш тип мультимедиа. Например, он знает, что:
- Ваш тип мультимедиа имеет свойство links, в котором перечислены доступные / связанные ссылки.
- Каждая ссылка идентифицируется отношением (точно так же, как браузеры знают, что ссылка [rel = "stylesheet"] означает, что это таблица стилей, или rel = favico - это ссылка на favicon ...)
- и он знает, что означают эти отношения («компании» означают список компаний, «поиск» означает шаблонный URL для поиска по списку ресурса, «отделы» означают отделы текущего ресурса)
Ниже приведен пример обмена HTTP (тела в yaml, так как их легче написать):
Запрос
GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml
Ответ: список ссылок на основной ресурс (компании, люди, что угодно ...)
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
Запрос: ссылка на компании (используя body.links.companies предыдущего ответа)
GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml
Ответ: неполный список компаний (по пунктам), ресурс содержит связанные ссылки, например ссылку, чтобы получить следующую пару компаний (body.links.next), другую (шаблонную) ссылку для поиска (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
Таким образом, как вы видите, если вы идете по пути ссылок / отношений, то, как вы структурируете часть пути ваших URL, не имеет никакого значения для вашего клиента API. И если вы сообщаете клиенту структуру ваших URL-адресов в качестве документации, то вы не выполняете REST (или, по крайней мере, не уровень 3 в соответствии с « моделью зрелости Ричардсона »)