Каков наилучший способ назвать ресурсы REST при возврате одного и того же ресурса, но с использованием другого DTO?

Question

Мне интересно, каков наилучший способ вернуть один и тот же ресурс, но с использованием разных DTO. Например, у меня есть класс пользователя:

public class User {
   private String name;
   private String surname;
   private String age;
}

Список пользователей доступен по URL:

/users

Некоторым другим пользователям необходим просмотр списка пользователей, но без возраста, поэтому я хотел бы вернуть список UserDTO.

public class UserDTO {
   private String name;
   private String surname;
}

Как правильно определить URL?

/userDtos - this is bad, because I can have more than one DTOs for representing users,
/users/dto - this is also bad
/users?name=true,surname=true - this one is also bad, it indicates that we are filtering the result, but we are not; we're just filtering fields.

Наверняка кто-то уже имел эту проблему раньше, но я не смог найти что-нибудь на Inte rnet.

Answer 1

Аналогичная концепция называется частичным ответом, которая позволяет клиенту указать, какие поля включить в ответ, используя параметры запроса, такие как:

/user?fields=name,surename

По сути, вы определяете собственный синтаксис язык запросов для представления выбора полей. Здесь и Google Cloud API являются некоторыми примерами.

Поднимая эту концепцию на более грубый уровень, вы можете использовать параметр запроса "view" для определения различных предопределенная комбинация полей, таких как:

/users              //default view if no "view" query parameter is specified
/users?view=admin   //maybe this view will not show age field
/users?view=hr      //maybe this view only show the fields that are accessible to HR