Как безболезненно раскрыть ресурсы связанных родительских и дочерних объектов?

Question

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

# These are for CRUD the search definitions, not running the searches
1. /users/{username}/searches # lists the searches for a user
2. /users/{username}/searches/{search-name} # CRUD a specific user search
3. /groups/{groupname}/searches # lists the searches for a group
4. /groups/{groupname}/searches/{search-name} # CRUD a specific group search
5. /searches/{search-id|search-name}
6. /searches/group/{groupname}/{search-name}
7. /searches/user/{username}/{search-name}

Я не считаю правильным выставлять все эти URI. Это означает, что есть два способа обновить или отобразить результаты поиска для пользователя и группы: через / groups / search или через / search / group. Это также означает больше поддержки, и я боюсь, что возникнут тонкие различия.

Поиски могут быть независимыми записями в базе данных и не привязываться к конкретному пользователю или группе (например, системные поиски по умолчанию или контекстно-зависимые поиски).

Поскольку поиски могут быть независимыми, неправильно выставлять их как /users/searches и /groups/searches. В то же время, если я думаю: «Что такое поиски Боба?» Сначала я бы подумал о /users/bob/searches, потому что, логически, это bob search. Точно так же, если я хочу, скажем, сделать резервную копию учетной записи Боба, вся его личная информация должна быть в /users/bob.

Итак, есть ли у кого-нибудь совет о том, какой путь предпочтителен и / или хорошо (или плохо) работает для них?

Answer 1

Я бы хотел придерживаться

5. /searches/{search-id|search-name}
6. /searches/group/{groupname}/{search-name}
7. /searches/user/{username}/{search-name}

Проблема с резервным копированием может быть решена путем создания нового ресурса, который содержит ссылки на информацию Боба по всей системе, например,

GET /AccountData/Bob

<div class="AccountData">
   <link rel="searches" href="/Searches/User/Bob"/>
   <link rel="options" href="/Options/User/Bob"/>
   <link rel="usagehistory" href="/History/User/Bob"/>
</div>

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

Я бы предложил вам больше сосредоточиться на том, какие ссылки будут возвращаться в представлениях.

, например

GET /Groups/{GroupName}

<div class="group">
  <div class="name">AGroup</div>
  <link rel="searches" href="/Searches/Group/AGroup"/>
</div>

При таком подходе вы гораздо меньше заботитесь о том, как выглядит структура URL. Как говорит Рой здесь

REST API не должен определять фиксированный Имена ресурсов или иерархии ( очевидная связь клиента и сервера)

Я понимаю, что это может показаться экстремальной позицией, учитывая, что все в SO кажутся зацикленными на том, как должны выглядеть ваши URL, чтобы иметь RESTful API, но чем больше вы об этом думаете, тем больше в этом смысла.

P.S. Пожалуйста, не зацикливайтесь на моем выборе HTML в качестве медиа-типа для представлений, я просто обращаю внимание на тот факт, что вам не всегда нужно использовать собственный словарь XML.

Answer 2

Поиск - это функциональность, а не ресурс, поэтому его не следует использовать в ресурсах. URI может быть в параметре, например

/users/{username}?q={query string}
/groups/{groupname}?q={query string}

, тогда для этой строки запроса у вас есть 2 варианта

 "RQL" (Resource Query Language)

или

"FIQL" (Feed Item Query Language)

Answer 3

Моя тенденция состоит в том, чтобы разделить на типы запросов (например, один тип запроса - это запрос "поиска по списку". Тогда у меня будут аргументы. Например, searchlist? User = john. Если вы не пытаетесь сделать так, чтобы эти вещи индексировались ботами и поисковыми системами, это должно работать нормально.