Should I allow sending complete structures when using PUT for updates in a REST API or not?
- by dafmetal
I am designing a REST API and I wonder what the recommended way to handle updates to resources would be. More specifically, I would allow updates through a PUT on the resource, but what should I allow in the body of the PUT request?
Always the complete structure of the resource?
Always the subpart (that changed) of the structure of the resource?
A combination of both?
For example, take the resource http://example.org/api/v1/dogs/packs/p1.
A GET on this resource would give the following:
Request:
GET http://example.org/api/v1/dogs/packs/p1
Accept: application/xml
Response:
<pack>
<owner>David</owner>
<dogs>
<dog>
<name>Woofer</name>
<breed>Basset Hound</breed>
</dog>
<dog>
<name>Mr. Bones</name>
<breed>Basset Hound</breed>
</dog>
</dogs>
</pack>
Suppose I want to add a dog (Sniffers the Basset Hound) to the pack, would I support either:
Request:
PUT http://example.org/api/v1/dogs/packs/p1
<dog>
<name>Sniffers</name>
<breed>Basset Hound</breed>
</dog>
Response:
HTTP/1.1 200 OK
or
Request:
PUT http://example.org/api/v1/dogs/packs/p1
<pack>
<owner>David</owner>
<dogs>
<dog>
<name>Woofer</name>
<breed>Basset Hound</breed>
</dog>
<dog>
<name>Mr. Bones</name>
<breed>Basset Hound</breed>
</dog>
<dog>
<name>Sniffers</name>
<breed>Basset Hound</breed>
</dog>
</dogs>
</pack>
Response:
HTTP/1.1 200 OK
or both? If supporting updates through subsections of the structure is recommended, how would I handle deletes (such as when a dog dies)? Through query parameters?
