HATEOAS - How to model link relations that change state

Question

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"?

Answer 1

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.

Answer 2

You have to describe forms somehow. You "verbose" solution is perfectly okay:

{
  rel: 'cancel',
  href: '/orders/12/',
  type: 'PUT',
  values: {
    state: 'cancelled'
  }
}

note: you have to define a custom MIME type or use a generic MIME type which is capable of describing forms (e.g. collection+json), or which an RDF type (which supports REST vocabs like Hydra) - aka. uniform interface / self-descriptive messages

I would like to represent available actions there since, for example, cancelling an order isn't always possible ('completed' state).

If an operation is not available, then don't send a link pointing to that operation.