RESTful дизайн ресурса с бинарными состояниями

Question

У меня есть ресурс, который по сути является простым документом CRUD, который имеет небольшой поворот в том, что его можно «переключить» в «синхронизированное» состояние, где вместо использования своих текущих значений он теперь возвращает значения «родительский» документ, с которым он теперь синхронизирован.

Я пытаюсь найти ОТЛИЧНЫЙ способ моделирования этого. У ресурса есть свойство, которое указывает это состояние Synchronzied = true/false, и свойство ParentId, указывающее, с каким ресурсом он синхронизируется.

Один из вариантов - просто разрешить это изменить во время обновлений PUT, но это выглядит как-то неправильно, поскольку это не часть документа, а в некотором отношении метаданные о документе. Я также рассмотрел запрос POST /document/{id}/synchronized, в котором запрашиваемое состояние передается в качестве аргумента.

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

Answer 1

В ответ на GET для синхронизированного ресурса вы можете рассмотреть возвращение 302/303 с заголовком Location, установленным для родительского ресурса.Но затем разрешите PUT на том же синхронизированном URI заменить перенаправление на переданный объект, который затем будет возвращен в последующих ответах GET.Если вы хотите разрешить клиентам переключать сущность обратно в синхронизированное состояние, вы можете сделать это, поместив в дочерний URI тело запроса, содержащее URI нужного родителя.Вы можете даже найти случайные случаи использования, разрешив клиенту POST любой URI, а не только идентификатор небольшого набора известных родителей.

GET /child
    200 OK
    {foo: bar}

POST /child
{parent: /some/other}
    200 OK

GET /child
    302/303
    Location: /some/other

PUT /child
{foo: baz}
    201 Created

GET /child
    200 OK
    {foo: baz}

Answer 2

Одним из решений здесь является наличие двух разных типов ресурсов - полных документов и ведомых документов - различаемых по типу MIME.Например, у вас может быть application/vnd.mysite.document для полного документа и application/vnd.mysite.documentlink+json, когда вы просто ссылаетесь на другой документ.

Чтобы сделать ведомый документ:

PUT /document/1234
Content-Type: application/vnd.mysite.documentlink+json

{"parent": "/document/1"}

Чтобы сделатьполный документ:

PUT /document/1234
Content-Type: application/vnd.mysite.document

Hello, I am a document full of stuff.

Затем вы можете ответить на GET запросы, вернув документ или перенаправив 303 (см. другие) к родителю.

Answer 3

Вы рассмотрели большинство распространенных вариантов, однако рассмотрите возможность использования HTTP PATCH метода . Я успешно использовал его через AJAX на Firefox и Chrome. Метод PATCH определяет набор изменений, которые будут применены к документу, а не заменяет весь документ (через PUT).

(Если вы хотите только получить часть документа, рассмотрите возможность указания Range заголовка с GET. Вам нужно будет определить что-то отличное от диапазона байтов для работы с документами XML или JSON - см. подробности о единицах измерения диапазона .)

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