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

Question

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

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

GET /persons/12 

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

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

GET /persons/840212-3321 

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

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

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

Answer 1

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

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

/users/12 

и

/users/morgan 

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

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

Как вы можете видеть, я предпочитаю множественные сегменты URI ;-)
я думаю о «работе 123», как из «рабочих мест» коллекции, так что кажется логичным, чтобы иметь «рабочие места» ресурс, с subresources для каждой работы.

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

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

у меня есть что-то подобное, но использовать только первая буква в качестве фильтра:

/sites?alpha=f 

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

Answer 2

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

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

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

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

Несмотря на это, URL должен возвращать:

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

Однако я хотел бы также создать общий URL поиска, который возвращает список пользователей, которые соответствуют параметры (либо json-массив, либо любой другой формат, который вам нужен). Вы можете задать параметры поиска, как получить 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-адрес, как только вы его получите из поиска ...

Answer 3

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

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

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

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