Является ли хорошей практикой предоставление API агрегирования в Rest или в обычном WebAPI Design?

Question

Я предоставляю такой API REST для получения информации о базовом пользователе и информации о пространстве пользователя.

/v1/пользователей/{user_id}/профиль, который будет возвращать такой JSON:

`` `JSON {

"ID": 123, "Название":» Foo», "секс": 0, "электронная почта": "foo@gmail.com", } ` ``

/v1/пользователей/{user_id}/пространство, которые также возвращают JSON:

`` `{JSON "sum_space": 100, "used_space": 20, }

Теперь, если клиент (например, веб-страница, третье приложение) имеют представление, которое должно показывать часть информации о пользователе (например, «имя», «секс») и часть информации о пространстве пользователя (например, «sum_space») в одно и то же время. Должен ли я предоставить новый API агрегирования, такой как /v1/users/{user_id}?

И если я предоставляю такой API агрегирования, должен ли он возвращать все атрибуты пользователя и пространства? если бы я это сделал, возвращаемое значение будет включать некоторые неиспользованные значения, что увеличит пропускную способность сети. Но если этот API просто вернет то, что нужно клиенту, что мне делать, если придет новое требование клиента (например, просто введите имя пользователя и пользовательское_используемое пространство)?

Если я не предоставляю API агрегирования, все клиент должен называть N раз для получения N видов ресурсов. если есть требование для поиска фильтра (например, для получения списка пользователей, суммарное пространство> 100), клиент может делать это только последовательно.

Я очень смущаюсь по поводу того, что любое руководство следовать?

Answer 1

Укажите базовые данные /users/{id}. Разрешить клиентам включать необязательный параметр запроса ?expand=profile, space. Если они выбрали оба варианта, они получают подробный ответ с данными из всех трех конечных точек. Если они выбирают, скажем, profile, то получают базовые данные и данные профиля.

Если вам нужно, чтобы быть в состоянии ограничиться именно свойствами они нужны, вы также можете поддержать параметр ?include запроса, который может выглядеть GET /users/{id}?include=id,lastModifiedDate,profile.name&expand=profile и может вернуться что-то вроде

{ 
    "id": 25, 
    "lastModifiedDate": 0, 
    "profile": { 
     "name": "Bob Smith" 
    } 
} 

Вы можете бездельничать вокруг с структурой URI выше, как вам нравится. Возможно, вы предпочитаете GET /users/{id}?include=id,lastModifiedDate&expand=profile[name]. Дело в том, что вы можете использовать параметры запроса для определения типа возвращаемой вами информации.

Другим выбором, если вы используете типы MIME для конкретного поставщика, было бы использование другого типа mime для разных форм ответа. Один тип может возвращать профиль и пространство, а другой - только один или другой, когда запрос делается на GET /users/{id}. Это особенно тупой инструмент, и это не подходит для ваших нужд.