Как правильно ссылаться на связанные объекты в REST API?

Question

[Дмитрий Сергеев]

Ни как не могу понять каким образом мне отображать связанные объекты.
Просматривал API GitHab, сделал некоторые выводы, но реализовать их мне показалось не рационально...
Допустим есть 2 модели.
Заказы

1. Дата создания
   
2. Ссылка на клиента
   
3. Ссылка на работника
   

Клиенты

1. Дата создания
   
2. Username
   
3. Фамилия и инициалы
   

Кусок API GitHab

{
    "site_admin": false,
    "name": "The Octocat",
    "company": "GitHub",
    "blog": "http://www.github.com/blog",
}

Согласно GitHab я должен сделать так

{
    "id": 1,
    "create_at": "2016-04-29T19:37:03Z",
    "client": "client_ login",
    "user": "root"
}

Если мне нужно будет дополнительно достать USER то я делаю запрос к базе и достаю его, OK.
А если я выведу список всех заказов, а их например 100, то для получения информации о клиенте мне потребуется 100 запросов и 100 на юзире???
Оговорюсь, что запрашивать информацию о этих 2 связанных моделях обязательно.
Спасибо всем кто откликнулся!

Answer 1

[Anatoly Scherbakov]

1. Почему 100 запросов? Положим, вы хотите спросить список всех заказов.

GET /api/v1/orders/
[{
    "id": 1,
    "created_time": "2016-04-29T19:37:03Z",
    "client": "client_ login",
    "employee": "jane"
}, {
    "id": 2,
    "created_time": "2016-05-29T19:37:03Z",
    "client": "another_client",
    "employee": "john"
}, ...]

Непонятно кстати, у вас клиент, работник и юзер - это одно и то же или разные вещи? Зачем вы выводите в заказе user, если это свойство клиента, а не свойство заказа? Но суть одна: используется либо числовой, либо буквенный идентификатор для внешних сущностей.

Теперь вы можете сделать запрос по нужному вам клиенту:

GET /api/v1/clients/another_client/
{
    "id": 1,
    "created_time": "2016-04-29T19:37:03Z",
    "full_name": "Vasya Pupkin",
    "user": "bububum"
}

Если у вас сравнительно небольшое количество клиентов - ничего страшного в этом нет. Если у вас количество клиентов сопоставимо с числом заказов - вы можете вложенную сущность сделать, следующим образом:

GET /api/v1/orders/
[{
    "id": 1,
    "created_time": "2016-04-29T19:37:03Z",
    "client": {
        "id": 2,
        "full_name": "Vasya Pupkin"
    },
    "employee": "jane"
}, ...]

Вообще, на самом деле, в RESTful API полагается вместо id сущностей писать их URL, но оставим за скобками. Сам обычно так не делаю...

Comments

[Дмитрий Сергеев]

Если я захочу использовать URL, то все таки придется делать 100 запросов?

[Anatoly Scherbakov]

Если у вас действительно 100 клиентов - то очевидно да. Ну как альтернатива - вы можете запросить список всех клиентов к себе запросом /api/v1/clients/ и всё.

[Дмитрий Сергеев]

Anatoly Scherbakov: И в итоге потом сложить результат 2 запросов?

[Anatoly Scherbakov]

Дмитрий: да.