REST — поддержка нескольких возможных идентификаторов

Я думаю, что добавление сегмента/префикса пути - лучший ответ. Поскольку это уникальные вторичные ключи, это не то же самое, что поиск (который возвращает набор элементов), поэтому использование параметров запроса (которые не кэшируются) не кажется лучшим выбором.

Лично я планирую использовать префикс сегмента пути, разделенный "=", например, "name=" или "email=":

user/123456
user/name=john.doe
user/[email protected]

Функционально это эквивалентно добавлению сегмента пути (например, «пользователь/имя/john.doe»), но мне кажется, что это более точно соответствует концептуальной модели. Конечно, это незначительная деталь, поскольку RESTful API в любом случае не должны указывать фиксированную структуру URI.

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

user/name=john.doe/inbox/df87bhJXrg63

Такие платформы, как Java JAX-RS, поддерживают использование любого разделителя, который вы хотите:

@GET
@Path("user/{id}")
User getUser(@PathParam("id") UUID id);

@GET
@Path("user/name={name}")
User getUserByName(@PathParam("name") String name);

@GET
@Path("user/email={email}")
User getUserByEmail(@PathParam("email") String email);

Ваш первый вариант, вероятно, лучший.

Поиск пользователей по ID:

/users/id/48573

Поиск пользователей по короткому имени:

/users/name/thisisausername

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

Другой вариант, который я встречал довольно часто, — это использование параметров запроса, подобных следующему:

/users?id=48573
/users?name=thisisausername

Я думаю, что первый выглядит немного чище и читабельнее.

Довольно старый вопрос, но у меня было то же самое, и я наконец нашел решение: используйте регулярное выражение в параметре пути.

Вот как я закодировал этот вариант использования

@GET
@Path("/{id : \\d+}")
@Produces(APPLICATION_JSON)
public Response getById(@PathParam("id") long id) {
 <<your code>>
}

@GET
@Path("/{name}")
@Produces(APPLICATION_JSON)
public Response getByName(@PathParam("name") String name) {
 <<your code>>
}

Я бы подумал о квалификации строки с необязательным суффиксом:

/users/48573/id

/users/48573/name

Если вы получили строку без суффикса:

/users/48573

затем вы проверяете строку и видите, является ли это идентификатором или именем.

Если вы получаете только действительный идентификатор, но не имя, то это поиск по идентификатору, эквивалентному:

/users/48573/id

Если вы возвращаете только имя, то это поиск по имени, эквивалентный:

/users/48573/name

Если вы можете получить значение по идентификатору или имени, вы возвращаете ошибку ответа 300 и возвращаете клиенту ссылки на обе возможности:

/users/48573/id

/users/48573/name

Устаревшие потребители продолжают работать «как есть», за исключением случайного появления повторяющихся пар идентификатор/имя, когда они получают новую ошибку ответа 300.

Ваш API не является RESTful, если это проблема. Чтобы цитировать Роя Филдинга:

REST API не должен определять фиксированные имена ресурсов или иерархии (очевидная связь клиента и сервера). Серверы должны иметь свободу управлять своим собственным пространством имен. Вместо этого разрешите серверам инструктировать клиентов о том, как создавать соответствующие URI, например, в HTML-формах и шаблонах URI, определяя эти инструкции в типах мультимедиа и связях. [Неудача здесь означает, что клиенты принимают структуру ресурсов из-за внеполосной информации, такой как стандарт для предметной области, который является ориентированным на данные эквивалентом функциональной связи RPC].

API REST следует вводить без каких-либо предварительных знаний, кроме исходного URI (закладки) и набора стандартизированных типов мультимедиа, которые подходят для целевой аудитории (т. е. ожидается, что их поймет любой клиент, который может использовать API). С этого момента все переходы между состояниями приложения должны управляться выбором клиента из предоставленных сервером вариантов, которые присутствуют в полученных представлениях или подразумеваются пользовательским манипулированием этими представлениями. Переходы могут определяться (или ограничиваться) знаниями клиента о типах мультимедиа и механизмах обмена ресурсами, оба из которых могут быть улучшены «на лету» (например, код по запросу). [Неудача здесь подразумевает, что внеполосная информация управляет взаимодействием, а не гипертекстом.]