Яка найкраща структура RESTful URL-адреси для рекурсивного ресурсу?

Я створюю RESTfull сервіс для деревоподібної структури ресурсів і цікавився, якою буде найкраща структура URL-адреси?

У мене є три вимоги:

вміти отримати колекцію кореневих ресурсів
вміти отримати індивідуальний ресурс
вміти отримати колекцію дитячих ресурсів

Моя поточна думка:

/rest/documents
/rest/documents/{id}
/rest/documents/{id}/documents

Я також думав про шлях однини / множини для позначення списків або окремих елементів, але я знаю, що у мене буде ресурс, такий самий множина, як і в однині, тому вирішив проти цього.

Хтось має думки з приводу вищезазначеного? чи мати інший / кращий спосіб структурування цього?

web-services

— Метт Брейлсфорд
джерело

Я, можливо, не розумію питання, але, як ми говоримо про URL, це SEO проблема?

— Джон Хопкінс

SEO - це не проблема, ні. Я в основному запитую найкращу логічну структуру URL-адреси для ресурсу, що само посилається.

— Метт Брейлсфорд

Це здається мені досить прямо вперед.

— Tim Post

Наскільки глибоко може йти ця структура?

— Мартійн Вербург

@Martijn глибина не обмежена

— Метт Брейлсфорд

Відповіді:

Що мені спадає на думку: не дозволяйте RESTful API відображати рекурсивність у самій URL-адресі. Подумайте, ваш ресурс - лише документи.

Якщо у вас зберігаються документи фізично відповідно до рекурсивної структури, створіть відображення унікального ідентифікатора та використовуйте ідентифікатор у URL-адресі:

/rest/documents/{id}

Тепер, якщо у вас є такі документи:

| Назва документа | DocumentPath | DocumentID |
--------------------------------------------
| abc | / abc | 1 |
| asd | / abc / asd | 2 |
| asd | / asd | 3 |
| бу | / abc / asd / boo | 4 |
| гей | / abc / asd / hey | 5 |

запит звертається до цієї URL-адреси для отримання /abc/asdдокумента

GET /rest/documents/2

Отже, тепер ви повинні надати користувачам свого API засоби для переходу вашої структури з невеликими зусиллями. Це можна зробити, обвівши ваш корисний вантаж відповіді (документ) в об'єкт, що містить додаткову інформацію про обхід, наприклад, такий:

{
   data: { /* your document goes here */ },
   parent: {"abc": 1 },
   children: [ { "boo": 4 }, { "hey": 5} ]
}

за умови, що ви очікуєте, що користувачі не створюватимуть занадто багато документів на одному рівні, ви можете включити у відповідь список дітей. Якщо це не так, ви можете запропонувати користувачеві отримати такі ідентифікатори дочірнього документа, як, наприклад, для підкачки результатів через параметри запиту:

GET /rest/documents/2/children?page=2&size=50

Нарешті, кажучи про параметри запитів, ви також можете подавати інформацію про шлях безпосередньо через параметри запиту:

GET /rest/documents?path=somepath&page=1&size=42

Усі згадані підходи очікують, що звичайна GET /rest/documentsповертає лише кореневі документи.

— сітки
джерело

Гарна ідея. Однак відношення до дочірніх документів не зрозуміло в API, якщо дочірні документи включені у відповідь на документ. Якщо в документах також є інший підресурс, наприклад коментарі, ви зазвичай отримуєте доступ до питань для документа, використовуючи / dokumenti / {id} / questions. Для того, щоб бути послідовними та чіткіше стосунки до дочірніх документів зрозумілі в API, я б запропонував, щоб дочірні документи мали доступ до / документа / {id} / дочірні документи. Повідомлення, що повертаються, будуть Документами, як / документи / {id}. Отже, все ще працює те, що ви описали тут.

— Натан Уорд

Можливо, щось подібне:

/rest/{rootEntity}/Item/{leafEntity}/{id}
/rest/{entity}/ItemList
/rest/{entity}/ItemList/{leafEntity}

де {rootEntity} є початковою точкою вашої колекції, {leafEntity} - це будь-який названий вузол листя у вашому дереві.

Ви можете додати кілька параметрів будь-якого з перерахованих вище, щоб вибрати, скажімо, Останні або Усі або щось подібне.

— Гері Роу
джерело