Question

I have a resource which is essentially a simple CRUD document which has a small twist in that it can be “switched” into a “synchronized” state where-in instead of using it’s own current values it now returns the values of a “parent” document that it is now synchronized with.

I am trying to find a RESTful way to modeling this. The resource has a property which indicates this state Synchronzied = true/false and a ParentId property to indicate which resource it is synced with.

One option is to just allow this to be changed during the PUT updates but that feels somehow incorrect as this isn’t a part of the document but in some respect is metadata about the document. I’ve also considered a POST /document/{id}/synchronized request where the requested state is passed as an argument.

Neither feels quite right though. The first feel a bit awkward because it feels as if I’m parsing the submitted data for just one value, the rest are essentially discarded if we are synchronizing. In the second case it feels wrong to be creating a nested resource just for one property.

Answer 1

One solution here is to have two different resource types – full documents and slave documents – distinguished by MIME type. For example, you could have application/vnd.mysite.document for the full document and application/vnd.mysite.documentlink+json when you’re just linking to another document.

To make a slave document:

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

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

To make a full document:

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

Hello, I am a document full of stuff.

Then you can respond to GET requests by returning the document or a 303 (See Other) redirect to the parent.