Should I allow sending complete structures when using PUT for updates in a REST API or not?

Posted by dafmetal on Stack Overflow See other posts from Stack Overflow or by dafmetal
Published on 2010-04-27T08:05:58Z Indexed on 2010/04/27 9:43 UTC
Read the original article Hit count: 368

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?

  1. Always the complete structure of the resource?
  2. Always the subpart (that changed) of the structure of the resource?
  3. 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?

© Stack Overflow or respective owner

Related posts about rest

Related posts about restful