I have been thinking a lot about Hypermedia REST-APIs for the last couple of weeks. One thing I am not quite sure about is how I want to model side effects on the server side.
In my current project, I am using JSON+HAL as the content-type, and am making use of links and embedded resources.
For example: Let’s say some resource A gets PATCHed by the client, e.g. because a money value gets updated. Suppose this resource is used by another resource B. This resource B represents the sum of all resources that are of A’s kind. Hence resource B would have provide a new value after A has been updated. What’s the best way to communicate this to the client? The following options come to my mind:
- Return all possibly updated links in the PATH response, i.e. especially a link to B. The client will then try to GET all provided links.
- Embed those resources that may have been updated, and provide links to all other relevant resources.
- Return a link to a parent resource of both A and B, because the whole state of A and B has been changed, and possibly even more.
Option 1) seems not right, because I may provide links to resources that are not really in the vicinity of A. Also, I cannot distinguish between resources that I should GET because they were updated, and resources that may be useful in other ways (for navigation, manipulating application state, creating new resources, …)
Option 2) is basically the same as 1), but with the advantage that an embedded resource tells me directly the state of the resource, which is useful when I embed B.
Option 3) sounds the best to me so far. In this example I might have a parent resource “spreadsheet”, which contains row resources, like A, and a sum resource, like B. If I change one of the rows, I get a link back to the spreadsheet, which the client can then GET, and either get all rows and sums embedded or as links.
Maybe I am missing some other options. I am really not sure what the best practice here is.
So now I found out that you can actually signal changes in the link relation types. The RFC for link rels allows you to specify more than one link relation per link:
{
_links : {
"sum-of-rows has-changed" : { "href" : "http://..." },
"some-other-link" : { "href" : "http://..." }
}
"value" : 5000.0
}
In this case the has-change rel notifies the client that the resource behind that link has changed and should be refreshed.