Update a single property in a REST API

rest restapi
ski_junkie picture ski_junkie · Feb 20, 2014 · Viewed 18.6k times · Source

In designing a new API, we are doing our best to follow the patterns established by REST. The question I have is the best method to follow when trying to update a single property. For example:

Imagine you have a simple Car resource:

{
   "make": "Chevrolet",
   "model": "Chevelle",
   "year": 1966,
   "color": "black",
   "for_sale": true
}

Let's assume that the property for_sale is something that you anticipate will be updated regularly by the user. I have a couple options:

  1. PUT the entire resource with for_sale set to false. For a reasonably small resource, this seems fine, however, in most cases our resources are quite large so a lot of waste in sending the entire resource to update a single, often changed property.

  2. POST and do a partial update by only including the element to update, such as: {"for_sale":false} This is better as it requires a lot less overhead.

But I somehow seem to be reaching for something even more simple, but I don't seem to find the right approach. It would be quite convenient to offer a simple PUT to a URL (that doesn't require any request body) to update this property. I see what Google is doing in their API to accomplish this, but it feels just a bit RPC-ish, although I like the simplicity.

POST /blogs/blogId/posts/postId/comments/commentId/approve (marks a comment as not spam)

POST /blogs/blogId/posts/postId/comments/commentId/spam (marks a comment as spam)

Can someone offer some advice on the best way to approach updating a single property within a resource (in a preferably lightweight manner) that followed REST principles?

Answer

Software Engineer picture Software Engineer · Feb 20, 2014

Actually, I think that the PATCH method is designed specifically for this purpose. You should use it to provide a partial update to the object, rather than a full update. Here is a blog entry that explains this in more detail.

Related questions

What is a good way to transfer binary data to a HTTP REST API service?

We are extending our HTTP REST API to allow clients to upload picture (for the purpose of this question, assuming binary data). So far we have only allowed simply strings in our API parameters. What is a good way to …

Read More
Python post request with Bearer token

Im trying to make a script that post data on REST service together with Bearer token. Here is working PHP example: $postData = array( 'app' => 'aaaa' ); $ch = curl_init($apiUrl); curl_setopt_array($ch, array( CURLOPT_HTTPHEADER, ['Authorization: Bearer '.$…

Read More
Which HTTP response code for "This email is already registered"?

I'm creating a RESTful API for creating users that enforces unique email addresses: Successful POST /users: HTTP 201 Created If I POST the same email address again, what should the response code be? Is 409 Conflict the appropriate response code?

Read More