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

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

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

/users/id/48573

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

/users/name/thisisausername

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

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

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

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

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

/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].

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