Updating a single field for a resource with the PATCH method

As we explained in Chapter 2, Working with Class-Based Views and Hyperlinked  APIs in Django, our API can update a single field for an existing resource, and therefore, we provide an implementation for the PATCH method. For example, we can use the PATCH method to update an existing game and set the value for its played field to true. We don't want to use the PUT method because this method is meant to replace an entire game. The PATCH method is meant to apply a delta to an existing game, and therefore, it is the appropriate method to just change the value of the played field.

Now, we will compose and send an HTTP request to update an existing game, specifically, to update the value of the played field and set it to true because we just want to update a single field, we will use the PATCH method instead of PUT. Make sure you replace 2 with the id or primary key of an existing game in your configuration:

http PATCH :8000/games/2/ played=true

The following is the equivalent curl command:

curl -iX PATCH -H "Content-Type: application/json" -d '{"played":"true"}' :8000/games/2/

The preceding command will compose and send a PATCH HTTP request with the specified JSON key-value pair. The request has a number after /games/, and therefore, it will match '^games/(?P<pk>[0-9]+)/$' and run the patch method for the views.GameDetail class-based view. Remember that the method is defined in the RetrieveUpdateDestroyAPIView superclass and it ends up calling the update method defined in mixins.UpdateModelMixin. If the Game instances with the updated value for the played field are valid and were successfully persisted in the database, the call to the method will return a 200 OK status code and the recently updated Game serialized to JSON in the response body. The following lines show a sample response:

HTTP/1.0 200 OK
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Date: Sun, 26 Jun 2016 04:09:22 GMT
Server: WSGIServer/0.2 CPython/3.5.1
Vary: Accept, Cookie
X-Frame-Options: SAMEORIGIN
{
 "game_category": "3D RPG", 
 "name": "PvZ Garden Warfare 4", 
 "played": true, 
 "release_date": "2016-06-21T03:02:00.776594Z", 
 "url": "http://localhost:8000/games/2/"
}