Як створити кінцеві точки API для розміщення дочірнього об'єкта та отримання всіх дітей усіх батьків?

Наприклад, у мене є організації: Клієнт, Звіт. У клієнта може бути багато звітів, і я думаю, що кінцева точка для одного управління звітом має бути вкладена так:

/clients/{client_id}/reports/{report_id}

Що стосується всіх звітів одного клієнта, то очікується:

/clients/{client_id}/reports

Але як має виглядати кінцева точка для отримання всіх Звітів усіх Клієнтів, щоб API підтримувався послідовно та добре розроблений.

Мої підходи:

1. (Я бачив це в деяких програмах google api) використовуйте замість нього "-" і розбирайте його як "все":

/clients/-/reports

Це підтримує формат кінцевої точки однаковий, але виглядає трохи незвично, не може знайти жодного rfc, який пропонує такий спосіб.

2. Створіть окрему кінцеву точку лише для всіх звітів:

/reports

Але для отримання звітів клієнта все одно:

/clients/{client_id}/reports

3. Кінцеві точки Refactor, щоб зробити "клієнта" не батьківським, а просто параметром фільтра:

/reports?client={client_id} - звіти одного клієнта

/reports - звіти всіх клієнтів

У разі додавання нової кінцевої точки для публікації звіту для конкретного клієнта, це може виглядати некрасиво, оскільки це буде POST-запит з параметром у URL.

Чи є ще якісь пропозиції щодо ідей?

Але як має виглядати кінцева точка для отримання всіх Звітів усіх Клієнтів, щоб API підтримувався послідовно та добре розроблений.

Перш за все, пам’ятайте, що не існує золотих правил моделювання API RESTful. Все, що ми маємо, - найкращі практики та конвенції. При цьому, ймовірна відповідь - як зазвичай - вибирайте ту, яка найкраще відповідає вашим вимогам, і в цьому випадку найкращу, яка виражає вашу модель.

Тому перевірте три варіанти з виразності.

№1 Позначення "-"

Це яскрава ідея. Це дозволяє нам висловити умову всім, reportsщо належитьclients . Це звужує "запит" до певного набору звітів (тих, що знаходяться в межах clientsкордону).

Він постійно зберігає поняття ієрархії (приналежності), тому, якщо reportsйого можна знайти в різних місцях, ця позначення робить велику справу. Наприклад:

• Усі звіти, які належать клієнтам /clients/-/reports
• Усі звіти, що належать до відділів /departments/-/reports
• Усі звіти, які належать працівникам /employees/-/reports

Однак для отримання всіх доступних звітів у системі збереження ієрархії не дає жодної цінної переваги перед наступним варіантом.

№2 Різні URI

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

Новий URI ( /reports) також залишає відкритим можливість для управління звітами . Однак нам не потрібно надавати йому повну підтримку RESTful, якщо ми не вважатимемо це необхідним. Наприклад, ви заявили Make a separate endpoint just for all the reports. Це добре, вам потрібно лише реалізувати, GETі можливо, деякі фільтри для запитів, і все.

Зауважте, що ви все-таки могли це зробити /reports?client={client_id}. Мати різні URI для одного ресурсу - це добре. Деякі статті, які я прочитав, назвали б це надійністю .

# 3 Повернення ієрархії

Я відчуваю, що такий підхід не відповідає вашим очікуванням. Плюс, я думаю, це призведе вас зрештою до початкової точки.

Висновки

Зауважте, що №1 та №2 не є взаємовиключними. Ми можемо реалізувати і те, і інше. З огляду на реальну ситуацію та відповідно до приміщень ОП, я би реалізував лише №2.

^{1: це, /clients/-/reportsнапевно, еквівалентно}

Шаблони дизайну API Google пропонують використовувати "-" у цьому сценарії.

GET /clients/-/reports

Джерело:

https://cloud.google.com/apis/design/design_patterns#list_sub-collections