Як виглядають ваші URL-адреси, нічого спільного з REST не має. Щось іде. Насправді це "деталь реалізації". Тож так само, як ви називаєте свої змінні. Все, що вони повинні бути, - унікальне та довговічне.
Не витрачайте на це занадто багато часу, просто зробіть вибір і дотримуйтесь його / будьте послідовні. Наприклад, якщо ви йдете з ієрархіями, то ви робите це для всіх своїх ресурсів. Якщо ви перейдете з параметрами запиту ... тощо, так само як імена конвенцій у вашому коді.
Чому так ? Наскільки я знаю, API "RESTful" повинен бути доступним для перегляду (ви знаєте ... "Гіпермедіа як двигун стану програми"), тому клієнт API не переймається тим, якими виглядають ваші URL-адреси, поки вони дійсно (немає SEO, не існує людини, якій потрібно читати ці "дружні URL-адреси", за винятком випадків налагодження ...)
Наскільки приємна / зрозуміла URL-адреса в API REST цікаво лише вам як розробнику API, а не клієнту API, як і назва змінної у вашому коді.
Найголовніше - ваш клієнт API знає, як інтерпретувати ваш тип медіа. Наприклад, він знає, що:
- у вашому типі медіа є властивість посилань, яка містить список доступних / пов’язаних посилань.
- Кожне посилання ідентифікується відношенням (подібно до того, як браузери знають, що посилання [rel = "таблиця стилів"] означає його таблицю стилів, або rel = favico - посилання на фавікон ...)
- і він знає, що означають ці відносини ("компанії" означають список компаній, "пошук" означає шаблонний URL для пошуку за списком ресурсів, "відділи" означають відділи поточного ресурсу)
Нижче наводиться приклад обміну HTTP (тіла знаходяться в ямлі, оскільки простіше писати):
Запит
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 відповідно до " зрілості моделі Річардсона ")