Как правильно интерпретировать REST при получении разными идентификаторами? - PullRequest
Новая
       7

Как правильно интерпретировать REST при получении разными идентификаторами?

0 голосов
/ 17 ноября 2018

Я создаю REST API и хочу иметь самую чистую интерпретацию URI для доступа к ресурсам с использованием нескольких уникальных идентификаторов. Например, мой базовый POCO выглядит так: 

public class Account
{
  int AccountId { get; set; }
  string Mnemonic { get; set; }
  string LegacyId { get; set; }
  string Name { get; set; }
}

Первичным ключом является AccountId, и он предназначен в основном как внутренний идентификатор (также для использования в UX), но мнемоника также уникальна и предназначена для использования людьми (и для импорта из внешних систем). Также может существовать устаревший системный идентификатор, привязанный к более старой системе. При доступе к элементу по первичному ключу нет сомнений, что URI должен быть: 

GET: http://myserver/api/account/123

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

GET: http://myserver/api/account?query=EmergingMarkets

Мне кажется, что по сути это не ОТДЫХ, потому что это похоже на действие, а не на ссылку. Я использовал эту форму: 

GET: http://myserver/api/account/mnemonic/EmergingMarkets
GET: http://myserver/api/account/legacyId/EM10

Что является лучшей интерпретацией чистого ОТДЫХА. Есть ли другой вариант, не указанный выше?

Ответы [ 2 ]

0 голосов
/ 18 ноября 2018

Если вам не нужно показывать форму идентификатора http://myserver/api/account/123, и каждая учетная запись имеет уникальную мнемонику, форма http://myserver/api/account/ будет вполне допустимой, поскольку вы используете мнемонику в качестве идентификатора.Ничто в REST не указывает на то, что первичным ключом базы данных должен быть идентификатор, предоставляемый вашей службой.Все, что уникально идентифицирует ресурс, может быть использовано.

0 голосов
/ 17 ноября 2018

Я буду вторым Романом из комментариев. Существует несколько различных интерпретаций REST, но когда речь идет конкретно о «чистейшем», обычно я думаю, что вам нужно смотреть в сторону сервиса HATEOAS / Hypermedia, согласно первоначальному определению.

Это определение довольно слабое, потому что оно не устанавливает точный контракт о том, как должна выглядеть привязка с HTTP, но обычно принято, что URI должны обнаруживаться с помощью следующих ссылок, а не через внеполосную информацию. Клиенты не должны действительно жестко кодировать шаблоны URI, и есть несколько механизмов, которые особенно помогают при поиске (например, шаблонные ссылки HAL).

Итак, эти абзацы отвечают на ваш вопрос буквой, а теперь давайте ответим на то, что вы, вероятно, хотите знать: что такое элегантный дизайн URI для вашей конкретной задачи, который является предсказуемым и вменяемым с точки зрения разработки API.

Первое, что я хотел бы спросить: зачем вам вообще нужна форма 'id'? 

 http://myserver/api/account/123

123 - это некрасивый ключ и бессмысленный вид, если у вас нет прямого доступа к базе данных. Звучит так, как будто есть отношение 1: 1 к вашей «мнемонике», почему бы вообще не отбросить числовую форму и всегда использовать естественный ключ.

Это выглядит намного лучше, и устраняет проблему дублирования за один раз. Если это не вариант (возможно, не у каждой сущности есть «мнемоника»), и у вас должно быть 2 места для доступа к ресурсу, я думаю:

?query=x подсказывает мне, что это поиск, который может вернуть от 0 до n ресурсов в виде коллекции. Я бы лично избегал этого из-за уникальных, уникальных ресурсов. Это не действие , действие по-прежнему GET, поэтому для поиска это было бы хорошо.

Это оставляет /api/account/mnemonic/EmergingMarkets, хотя лично я бы поместил его в другое пространство имен, как /api/account. Поскольку api/account выглядит как коллекция, в которой все учетные записи являются участниками, api/account/mnemomic может выглядеть как другая учетная запись. Это говорит мне о том, что существуют две различные структуры, такие как: 

/api/account/id/123
/api/account/mnenomic/EmergingMarkets

Или: 

/api/account/123
/api/account-by-mnenomic/EmergingMarkets

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

Бонус

Если у вас есть 2 одинаковых ресурса, размещенных по 2 разным URL, есть несколько разных способов сказать клиентам, что они действительно одно и то же:

  1. Попросите 1 сделать перманентное перенаправление (308) к другому.
  2. Подайте ваш документ на оба сайта и используйте ссылку canonical, чтобы указать, что есть каноническое место для получения информации.
  3. Используйте заголовок Content-Location, чтобы сделать то же самое.
...