Информативный уникальный идентификатор в REST API

Разработка RESTful API. У меня есть два способа идентификации ресурсов (персональные данные). Либо уникальный идентификатор, созданный базой данных, либо номер социального страхования (SSN), введенный для каждого человека. SSN предположительно уникален, хотя может быть изменен.

Использование идентификатора было бы наиболее удобным для меня, так как оно гарантировано будет уникальным и не изменится. Следовательно, URL-адрес ресурса также всегда остается прежним:

GET /persons/12

{
  "name": Morgan
  "ssn": "840212-3312"
}

Аргумент использования SSN заключается в том, что он более информативен и понятен клиентам API. SSN также используется больше в окружающих системах:

GET /persons/840212-3321

{
  "name": Morgan
  "id": "12"
}

Таким образом, возникает вопрос: должен ли я идти с первым подходом и избегать некоторых головных задач реализации, в которых может измениться SSN. А может быть, какой-то вспомогательный метод, который преобразует из SSN в ID?

Или идите со вторым подходом. Предоставление более информативного API. Хотя нужно иметь дело с некоторыми не столь странными странностями, где URL: s может измениться из-за изменений SSN?

Ответ 1

Дизайн URL - это личный выбор. Но чтобы дать вам еще несколько примеров, которые отличаются от тех, которые уже предоставил Рэй, я дам вам некоторые из своих.

У меня есть ресурс учетной записи пользователя и разрешен доступ через оба URI:

/users/12

/users/morgan

где числовое значение является идентификатором auto_incremented, а буквенное значение является уникальным именем пользователя в системе, указанной пользователем. эти ресурсы недоступны, поэтому я не беспокоюсь о канонизации, однако страница /users ссылается на буквенные формы.

Никакие другие ресурсы в моей системе не имеют двух уникальных полей, поэтому их называют идентификаторы, /jobs/123, /quotations/456.

Как вы можете видеть, я предпочитаю множественные сегменты URI;-)
Я думаю, что "работа 123" относится к коллекции "jobs", поэтому представляется логичным иметь ресурс "jobs" с подресурсами для каждого задания.

Вам не нужно иметь отдельную область /search/ для выполнения поиска, я думаю, что было бы проще применить критерии поиска к ресурсу коллекции напрямую:

/people?ssn=123456-7890  (people with SSN matching/containing "123456-7890")
/people?name=morgan      (people who name is/contains "Morgan")

У меня есть нечто похожее, но используйте только первую букву в качестве фильтра:

/sites?alpha=f

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

Ответ 2

Приятно видеть, что кто-то занимает время, чтобы подумать об их URL-адресах ресурсов!

Я бы сделал Url с уникальным идентификатором, чтобы предоставить ресурс одному пользователю. Как:

http://api.mysite.com/person/12/

Где 12 - ваш уникальный идентификатор. Обратите внимание, что я также предпочитаю единственного "человека"....

Независимо от того, что URL должен вернуться:

{
  "ssn":  "840212-3312"
  "name": "Morgan"
  "id": "12"
}

Однако я бы также создал общий URL-адрес поиска, который возвращает список пользователей, которые соответствуют параметрам (либо json-массив, либо любой другой формат, который вам нужен). Вы можете указать параметры поиска как get params следующим образом:

 http://api.mysite.com/person/search/?ssn=840212-3312

или

 http://api.mysite.com/person/search/?name=Morgan

Они вернут что-то подобное для одного поискового запроса - обратите внимание на массив, а не на один элемент, например уникальный URL-адрес, который указывает прямо на одного пользователя.

[{
  "ssn":  "840212-3312"
  "name": "Morgan"
  "id": "12"
}]

Затем этот поиск может быть дополнен другими критериями поиска. Вы можете возвращать уникальный идентификатор только через URL-адрес поиска - вы всегда можете сделать запрос к уникальному URL-адресу URL, если у вас есть его из поиска...

Ответ 3

Я бы предположил, что вы не используете ни того, ни другого. Создавайте идентификаторы ресурсов, которые уникальны как для одного пользователя вашего API, так и для всех других ресурсов (включая ресурсы других пользователей).

Использование уникального идентификатора базы данных не является идеальным по нескольким причинам. Во-первых, ресурсы API и записи базы данных необязательно всегда будут от 1 до 1, даже если вы разработали его таким образом сегодня. Во-вторых, вы можете перейти в другое хранилище данных, которое будет генерировать уникальные идентификаторы разных форматов.

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

Один шаблон состоит в том, чтобы добавить уникальный идентификатор с несколькими символами, указывающими тип ресурса. Например, если пользователь является типом ресурса в вашем API, генерируемый уникальный идентификатор будет выглядеть как USR56382.