HATEOAS - How to model link relations that change state
hateoas, rel, rest
Solution
Modelling resources is the most difficult part of REST. Strictly adhering to the standard means if you see yourself ever doing this: `/resource/:id/{action}`, you're violating the "using HTTP correctly" criteria, as your endpoints should ideally always be "nouns', never "verbs" (the verbs are what the HTTP protocol provides).
So, while "it depends" (ie. the hard part of designing resources), typically: Object model states can be considered as resources themselves.
Which means, your order status is actually a resource you can query (either as a standalone `/orderstatuses` resource or as a sub resource eg. `/orders/:id/status`)
Your Application State can now link to the status resource based on the current status of the order itself. If your 'status' schema looks something like this (pseudo):
key: 'status'
values: ['pending', 'cancelled']
Your app could then `PUT /order/:id/status {status:'cancelled'}` (a well formed status) back to the API, which would then act to cancel your order. It's a little weird thinking in these terms (RPC is a lot more intuitive), but hopefully this helps.
Problem
Following HATEOAS principles that each states should be hyperlinked, what is the best way to model links that change resource state? Let's take classical example with orders: ``` { id : 12, state: 'pending', ..., links: [ ..., { rel: 'cancel', href: '/orders/12/cancel' }, ... ] } ``` I am not totall happy with that "/cancel" part - I would feel a lot better if I could send "PUT" request with contents: ``` { status:'cancelled' } ``` But how do I represent that with "href" attribute in links section? I would like to represent available actions there since, for example, cancelling an order isn't always possible ('completed' state). One possibility would be to use URL like '/orders/12?action=cancel' what it kinda feels like RPC approach and that I am missing something. Another possibility that looks probably nicest, would be to have links like that: ``` { rel: 'cancel', href: '/orders/12/', type: 'PUT', values: { state: 'cancelled' } } ``` This solution maybe feels a little bit verbose. Any ideas how to handle that gracefully? Maybe someone has already solved similar "problem"?