CODEWITHSUNDEEP
resthttpdomain-driven-designetagoptimistic-locking
M. Koch
M. Koch

Reputation: 822

RESTful - How to update a subresource and what ETag/payload to return concerning optimistic locking?

As an example I have an order where the invoicing address can be modified. The change might trigger various additional actions (i.e. create a cancellation invoice and a new invoice with the updated address).

As recommended by various sources (see below) I don't want to have a PATCH on the order resource, because it has many other properties, but want to expose a dedicated endpoint, also called "intent" resource or subresource according to the web links below:

/orders/{orderId}/invoicing-address

Should I use a POST or a PATCH against this subresource?

The invoicing address itself has no ID. In the domain layer it is represented as a value object that is part of the order entity.

What ETag should be used for the subresource?

The address is part of the order and together with the items they form an aggregate in the domain layer. When the aggregate is updated it gets a new version number in the database. That version number is used as an ETag for optimistic locking.

Should a GET on invoicing-address respond with the order aggregate version number or a hash value of the address DTO in the ETag header?

What payload should be returned after updating the address?

Since the resource is the invoicing address it seems natural to return the updated address object (maybe with server side added fields). Should the body also include the ID/URI and the ETag of the order resource?

None of the examples I found with subresources showed any server responses or considered optimistic locking.

https://rclayton.silvrback.com/case-against-generic-use-of-patch-and-put

https://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling

https://softwareengineering.stackexchange.com/questions/371273/design-update-properties-on-an-entity-in-a-restful-resource-based-api (see provided answer)

https://www.youtube.com/watch?v=aQVSzMV8DWc&t=188s (Jim Webber at about about 31 mins)

Upvotes: 0

Views: 686

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57279

As far as REST is concerned, "subresources" aren't a thing. /orders/12345/invoicing-address identifies a resource. The fact that this resource has a relationship with another resource identified by /orders/12345 is irrelevant.

Thus, the invoicing-address resource should understand HTTP methods exactly the same way as every other resource on the web.

Should I use a POST or a PATCH against this subresource?

Use PUT/PATCH if you are proposing a direct change to the representation of the resource. For example, these are the HTTP methods we would use if we were trying to fix a spelling error in an HTML document (PUT if we were sending a complete copy of the HTML document; PATCH if we were sending a diff).

PUT /orders/12345/invoicing-address
Content-Type: text/plain

1060 W Addison St.
Chicago, IL
60613

On the other hand, if you are proposing an indirect change to the representation of the resource (the request shows some information to the server, and the server is expected to compute a new representation itself)... well, we don't have a standardized method that means exactly that; therefore, we use POST

POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding, 2009

What ETag should be used for the subresource?

You should first give some thought to whether you want to use a strong-validator or a weak validator

A strong validator is representation metadata that changes value whenever a change occurs to the representation data that would be observable in the content of a 200 (OK) response to GET.

...

In contrast, a weak validator is representation metadata that might not change for every change to the representation data.

...

a weak entity-tag ought to change whenever the origin server wants caches to invalidate old responses.

I might use a weak validator if the representation included volatile but insignificant information; I don't need clients to refresh their copy of a document because it doesn't have the latest timestamp metadata. But I probably wouldn't use an "aggregate version number" if I expected the aggregate to be changing more frequently than the invoicing-address itself changes.

What payload should be returned after updating the address?

See 200 OK.

In the case of a POST request, sending the current representation of the resource (after changes have been made to it) is nice because the response is cacheable (assuming you include the appropriate metadata signals in the response headers).

Responses to PATCH have similar rules to POST (see RFC 5789).

PUT is the odd man out, here

Responses to the PUT method are not cacheable.

Should the body also include the ID/URI and the ETag of the order resource?

Entirely up to you - HTTP components aren't going to be paying attention to the representation, so you can design that representation as makes sense to you. On the web, it's perfectly normal to return HTML documents with links to other HTML documents.

Upvotes: 1

Related Questions