From 05e5111325bd2cbc15453c3173ba7e73f37fd7f6 Mon Sep 17 00:00:00 2001 From: Fredrik Liljegren Date: Mon, 21 Sep 2015 13:03:32 +0200 Subject: [PATCH] Adding description of PATCH. --- lessons/httpmethods.html | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/lessons/httpmethods.html b/lessons/httpmethods.html index 4156ad9..a8296b7 100644 --- a/lessons/httpmethods.html +++ b/lessons/httpmethods.html @@ -20,17 +20,17 @@ @@ -66,7 +66,7 @@
-

The HTTP verbs comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are POST, GET, PUT, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently. Of those less-frequent methods, OPTIONS and HEAD are used more often than others.

+

The HTTP verbs comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are POST, GET, PUT, PATCH, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently. Of those less-frequent methods, OPTIONS and HEAD are used more often than others.

Below is a table summarizing recommended return values of the primary HTTP methods in combination with the resource URIs:

@@ -92,10 +92,16 @@ - + + + + + + + @@ -113,6 +119,7 @@
  • POST
  • GET
  • PUT
    • +
  • PATCH
  • DELETE
    • @@ -151,6 +158,18 @@
  • PUT http://www.example.com/buckets/secret_stuff
    • +
    +

    PATCH is used for **modify** capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.

    +

    This resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to produce a new version. This means that the PATCH body should not just be a modified part of the resource, but in some kind of patch language like JSON Patch or XML Patch.

    +

    PATCH is neither safe nor idempotent. However, a PATCH request can be issued in such a way as to be idempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame. Collisions from multiple PATCH requests may be more dangerous than PUT collisions because some patch formats need to operate from a known base-point or else they will corrupt the resource. Clients using this kind of patch application should use a conditional request such that the request will fail if the resource has been updated since the client last accessed the resource. For example, the client can use a strong ETag in an If-Match header on the PATCH request.

    + +

    Examples:

    +
      +
    • PATCH http://www.example.com/customers/12345
      • +
    • PATCH http://www.example.com/customers/12345/orders/98765
      • +
    • PATCH http://www.example.com/buckets/secret_stuff
      • +
    +

    DELETE is pretty easy to understand. It is used to **delete** a resource identified by a URI.

    On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted item (often demands too much bandwidth), or a wrapped response (see Return Values below). Either that or return HTTP status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style response and HTTP status 200 are the recommended responses.

    PUTUpdateUpdate/Replace 404 (Not Found), unless you want to update/replace every resource in the entire collection. 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
    PATCHUpdate/Modify404 (Not Found), unless you want to modify the collection itself.200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
    DELETE Delete