what should response of REST full api for patch http method?

Question

I have an order resource on server. the url looks like http://example.net/order/1 the get method on above url will return whole order object like

    {
    "orderNo": "1",
    "status": "order place",
    "orderTimestamp": "2018-11-22 14:28:12",
   "invoiceAddress": {
        "salutation": "M",
        "firstName": "Dieter",
        "lastName": "Wolf",
        "companyName": "",
        "street": "Michaelkirchstr.",
        "houseNo": "16",
        "zipCode": "31604",
        "city": "Raddestorf",
        "countryIsoCode": "DEU",
        "phone": "05763 82 60 80",
        "email": "DieterWolf@armyspy.com"
    },
    "deliveryAddress": {}
    "items": [
        {
            ...
        }
    ],
    "returnItemsDetails": []
}

Now I wish to offer patch method on same api so one can update/add few details like delivery address. To update order detail one may request following request with patch http method on same order url

{
    "deliveryAddress": {
        "deliveryType": "CUSTOMER",
        "salutation": "M",
        "firstName": "Dieter",
        "lastName": "Wolf",
        "companyName": "",
        "street": "Michaelkirchstr.",
        "houseNo": "16",
        "zipCode": "31604 ",
        "city": "Raddestorf",
        "countryIsoCode": "DEU",
        "phone": "05763 82 60 80",
        "email": "DieterWolf@armyspy.com"
    }
}

My question is what should be there in response of patch request according to REST standard? or Is there any document where I can find about response data and format for REST api.

might be worth a look https://stackoverflow.com/questions/37718119/should-the-patch-method-return-all-fields-of-the-resource-in-the-response-body — codebrane, Feb 13 '19 at 10:33

score 8 · Answer 1 · edited Oct 07 '21 at 08:58

My question is what should be there in response of patch request according to REST standard? or Is there any document where I can find about response data and format for REST api.

According to RFC 5789 a successful response can return any success codes (i.e. 200 or 204). It should ideally also contain an ETag header to allow clients to track the current version for eventual consecutive requests (which is basically used for optimistic locking on the resources state).

The spec presents a 204 No Content sample as a patch consists, loosely speaking, of a set of instructions calculated by the client that a server should apply to transform the target resource to the desired state. So the client knows beforehand how the final result should look like and the server thus does not need to inform the client about it.

In case you want to return a 200 OK response I suggest returning a representation suggested by the Accept request header issued by the client (Content-Type negotiation) in order to avoid to force a client some predefined media type format it might not understand or reason further possibilities from.

If you need to apply unpredictable changes to a resource, i.e. based on some calculations done on the server side or include the payload to a certain predefined element (as probably done in your sample), RFC 5789 explicitly states that POST should be used instead of PUT or PATCH. Further note, that you could support application/merge-patch+json media format and its semantics defined in RFC 7386 to issue such a (sample) body as payload to a PATCH request and probably achieve your desired outcome, though.

score 2 · Answer 2 · edited Oct 07 '21 at 10:55

My question is what should be there in response of patch request according to REST standard? or Is there any document where I can find about response data and format for REST api.

Patch is defined in RFC 5789. Section 2 demonstrates that one possibility is that you will return an updated representation of the resource:

A response to this method is only cacheable if it contains explicit freshness information (such as an Expires header or "Cache-Control: max-age" directive) as well as the Content-Location header matching the Request-URI, indicating that the PATCH response body is a resource representation.

But I wasn't able to find a specification for the more general case. So what I would suggest is that one interpret the specifications from RFC 7231 for PUT and DELETE also be applied to PATCH

a representation of the status of the action

what should response of REST full api for patch http method?

2 Answers2