2. Tutorials
  3. Retrofit 2 — How to Update Objects on the Server (PUT vs. PATCH)

Retrofit 2 — How to Update Objects on the Server (PUT vs. PATCH)

In the Retrofit getting started tutorial you've learned how to create an Android app that connects to the public GitHub API. In following tutorials you've learned how to use OAuth to make requests as an authorized GitHub user. Finally, you've learned how to create new objects.

In this tutorial you'll learn how to update existing objects on the server. Most APIs utilize either a PUT or PATCH HTTP method for this task. If you're not familiar with HTTP requests yet, we recommend our tutorial on network basics.

If you're ready to go, let's start!

Retrofit Series Overview

  1. Getting Started and Creating an Android Client
  2. Basics of API Description
  3. Creating a Sustainable Android Client
  4. URL Handling, Resolution and Parsing
  5. How to Change API Base Url at Runtime
  6. Multiple Server Environments (Develop, Staging, Production)
  7. Share OkHttp Client and Converters between Retrofit Instances
  8. Upgrade Guide from 1.9
  9. Beyond Android: Retrofit for Java Projects
  10. How to use OkHttp 3 with Retrofit 1
  1. Synchronous and Asynchronous Requests
  2. Send Objects in Request Body
  3. Add Custom Request Header
  4. Manage Request Headers in OkHttp Interceptor
  5. Dynamic Request Headers with @HeaderMap
  6. Multiple Query Parameters of Same Name
  7. Optional Query Parameters
  8. Send Data Form-Urlencoded
  9. Send Data Form-Urlencoded Using FieldMap
  10. How to Add Query Parameters to Every Request
  11. Add Multiple Query Parameter With QueryMap
  12. How to Use Dynamic Urls for Requests
  13. Constant, Default and Logic Values for POST and PUT Requests
  14. Cancel Requests
  15. Reuse and Analyze Requests
  16. Optional Path Parameters
  17. How to Send Plain Text Request Body
  18. Customize Network Timeouts
  19. How to Trust Unsafe SSL certificates (Self-signed, Expired)
  20. Dynamic Endpoint-Dependent Interceptor Actions
  21. How to Update Objects on the Server (PUT vs. PATCH)
  22. How to Delete Objects on the Server
  1. Ignore Response Payload with Call<Void>
  2. Receive Plain-String Responses
  3. Crawl HTML Responses with jspoon (Wikipedia Example)
  4. Loading Data into RecyclerView and CardView
  1. Introduction to (Multiple) Converters
  2. Adding & Customizing the Gson Converter
  3. Implementing Custom Converters
  4. How to Integrate XML Converter
  5. Access Mapped Objects and Raw Response Payload
  6. Supporting JSON and XML Responses Concurrently
  7. Handling of Empty Server Responses with Custom Converter
  8. Send JSON Requests and Receive XML Responses (or vice versa)
  9. Unwrapping Envelope Responses with Custom Converter
  10. Wrapping Requests in Envelope with Custom Converter
  11. Define a Custom Response Converter
  1. Simple Error Handling
  2. Error Handling for Synchronous Requests
  3. Catch Server Errors Globally with Response Interceptor
  4. How to Detect Network and Conversion Errors in onFailure
  1. Log Requests and Responses
  2. Enable Logging for Development Builds Only
  3. Log Network Traffic with Stetho and Chrome Developer Tools
  4. Using the Log Level to Debug Requests
  5. Analyze Network Traffic with Android Studio Profiler
  6. Debug and Compare Requests with RequestBin
  1. Introduction to Call Adapters
  2. Custom Call Adapter to Separate OnResponse Callback
  3. How to Integrate RxJava 1.x Call Adapter
  4. How to Integrate RxJava 2.x Call Adapter
  5. How to Integrate Guava Call Adapter
  6. Custom Call Adapter to Separate Network and Gson Errors
  1. Pagination Using Query Parameter
  2. Pagination Using Link Header and Dynamic Urls (Like GitHub)
  3. Pagination Using Range Header Fields (Like Heroku)
  1. How to Upload Files to Server
  2. How to Upload Multiple Files to Server
  3. How to Upload a Dynamic Amount of Files to Server
  4. Upload Files with Progress
  5. Passing Multiple Parts Along a File with @PartMap
  6. How to Download Files from Server
  7. Download Files with Progress Updates
  8. How to Upload Files to Server
  1. Basic Authentication on Android
  2. Token Authentication on Android
  3. OAuth on Android
  4. Hawk Authentication on Android
  5. How to Refresh an Access Token
  1. Activate Response Caching (Etag, Last-Modified)
  2. Check Response Origin (Network, Cache, or Both)
  3. Force Server Cache Support with Response Interceptor
  4. Support App Offline Mode by Accessing Response Caches
  5. Analyze Cache Files
  1. Basics of Mocking Server Responses
  2. Customizing Network Behavior of Mocked Server Responses
  3. Mock APIs with JsonServer
  1. Callbacks
  2. Annotations
  3. Fluent Interface with Builders

Update Objects via an API

You already know how to create new objects: you send an object as the request payload to the server with a POST method. For example, you could send the following request, authenticated with an auth token, to create a new GitHub Gist:

POST /gists

{
  "description": "the description for this gist",
  "public": true,
  "files": {
    "file1.txt": {
      "content": "String file contents"
    }
  }
}

This would create a new public GitHub Gist object with a description and a file file1.txt. Of course, the payload completely depends on your API and the object you're creating. Nevertheless, most APIs expect a POST request for creating objects.

So how do you update an existing object? There are two different ways: PUT vs PATCH. We'll start with the more common one: PUT.

PUT Requests

PUT requests are used by the majority of the APIs. The request is actually very similar to creating a new object. You'll also send the full object to the server — even if you only change a single property. Furthermore, because you're sending a full object again, you need to tell the API that you want to update an existing object. Thus, the HTTP method changes from POST to PUT. Finally, you need to specify which object you want to update by stating the object ID.

For example, if you would want to update our GitHub Gist object (ID: 12343) from above, you would change the HTTP methods and update the payload to the change object.

PUT /gists/12343

{
  "description": "the NEW description for this gist",
  "public": true,
  "files": {
    "file1.txt": {
      "content": "String file contents"
    }
  }
}

In most cases this is how to update objects via an API. You use the PUT HTTP method, you specify the exact object (e.g., via an ID) and send the new object along. This new object replaces the existing one.

The API interface description with Retrofit would be straightforward:

public class Gist {  
    // all Gist properties  
      // ...
}

public interface GistService {  
    @PUT("gists/{id}")
    Call<ResponseBody> updateGist(@Path("id") String id, @Body Gist gist);
}

You've to imagine PUT less as updating and more as a replacing of existing objects. The downside is that for large objects this can become quite inefficient.

Let's image your GitHub gist has 1000 files and you only want to change the content of a single file, or just the description. Too bad, with PUT you would have to send a giant request with all files to the server. GitHub Gists are a primary example where PUT is at its limits. That's why GitHub actually doesn't offer PUT for Gists. Instead, you've to use PATCH requests, which we'll look at next.

PATCH Requests

PATCH requests have the exact same goal as PUT requests. You want to update an existing object on the server. However, the approach between PUT and PATCH is different. PUT requests replace the entire object. On the other hand, PATCH requests only send the changed properties, and ignore everything that stays the same.

For example, if we would update the description of our Gist, we would send this request with a much smaller payload: 

PATCH /gists/12343

{
  "description": "the NEW description for this gist"
}

Please note how the HTTP method URL still contains the ID of the object. Consequently, the Retrofit implementation would be almost identical:

public class Gist {  
    // all Gist properties  
      // ...
}

public interface GistService {  
    @PATCH("gists/{id}")
    Call<ResponseBody> updateGist(@Path("id") String id, @Body Gist gist);
}

The biggest difference for clients is that they've to make sure they're aware of the changed properties and creates a matching Java object, and subsequent payload.

In our Gist example we would need to create a new Gist object where we don't send anything besides the updated description property. Be careful, you often cannot send properties as null, which have not changed! Null properties are understood as "delete this". For example, if we would want to change the description of our Gist and delete the existing file file1.txt, this request would do it:

PATCH /gists/12343

{
  "description": "the NEW description for this gist",
  "files": {
    "file1.txt": null
  }
}

In summary, make sure Retrofit isn't automatically sending null properties in your payload to avoid negative surprises.

As you can see just with the small Gist example, PATCH requests are usually more efficient on the network. However, the logic for clients becomes a little more complicated, because they've to be aware which and how properties changed. Of course, in doubt, the client could just send a full object as a PATCH request and essentially mimic a PUT request. That would work just fine, but lose the network efficiency effect of PATCH.

GitHub opted to only offer the PATCH method with their Gist API. However, with other APIs you might find either, or just one of the methods.

Summary

In this tutorial you've learned how to update objects on the server. You've seen two different approaches: PUT to replace existing objects, and PATCH to selectively change object properties. Either way has its advantages and, unfortunately, as the app developer you often don't have a choice. Nevertheless, with this tutorial at hand you know can handle both without any issues!

Do you have further questions on this topic or about Retrofit in general? Just let us know on Twitter @futurestud_io or leave a comment below.

Enjoy coding & make it rock!

Norman Peitek

android & node.js dev

https://twitter.com/peitek

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous