rest - HATEOAS and links/actions -

i'm trying wrap head around how (and if to) implement hateoas in api. 1 of concept of feeding client actions appropriate in current situation. i'm not sure if i'm implementing idea correctly.

let's have resource type order status can changed, can have different statuses (processing, accepted, declined, expired, successful). should create following json object:

{     ...     "links": {         "accept": "http://example.com/order/1/accept",         "decline": "http://example.com/order/1/decline"     } } 

or creating unnecessary actions here? , if above correct, should status changed patch, or get? , if patch, how 1 know (defeating purpose of hypermedia)?

edit: forgot add order id

let's have resource type order status can changed, can have different statuses (processing, accepted, declined, expired, successful).

warning: unless domain happens document management, may getting tangle if try match resources domain concepts. jim webber warned years ago; in cases, resources part of integration domain. little digital pieces of paper used interact domain model.

{     ...     "links": {         "accept": "http://example.com/order/accept",         "decline": "http://example.com/order/decline"     } } 

the basic idea here fine - if client wants invoke accept protocol, know link use; likewise decline protocol. else, client knows shouldn't trying because links not available; instance, if goal of client expire order, know had run dead end.

the spelling of uri here bit strange; client shouldn't need care spelling, request should stateless. if order type of resource, how communicating order accept/decline.

and if above correct, should status changed patch, or get?

neither.

get wrong, because advertising resource supports claim operation safe, means intermediary components can speculatively follow link, pre-loading result save client time. not want doing if understanding message communicate decision made client

patch has 2 issues. first, it's designed document manipulation; if application document database, patch fantastic making 1 or several scoped changes. it's not great dealing proxy representations of business model; instead of client communicating intent server, client communicates side effect intent have on representation, , server tries deduce intent side effect.

but potentially around that; after all, can choose media types support, , potentially limit types allow express client's intent.

the second issue patch not idempotent; has same failure modes post -- if request isn't acknowledged server, client's cannot readily determine if safe retry request.

the straight forward approach think of edits analogous putting hand written note somebody's inbox

order 54321 should accepted. please done. signed, client.

in other words, aren't trying manipulate order resource directly, instead delivering note inbox have side effect of manipulating order. client describes change wants, server makes change (or not, if allowing server have autonomy).

for approach, put (which idempotent) or post (which not) appropriate. in effect, adding new message inbox collection, , can use idiom choose suitable method.

and if patch, how 1 know (defeating purpose of hypermedia)?

how client know links in "links" property?

how browser know links in html document?

the rest answer is: know because you've invested bunch of effort in designing media type itself. in case of web, bunch of time , effort invested in designing text/html media type, , client designed html in mind can consume representation produced server shares understanding -- client , server decoupled each other, share common ground.

in case of html, part media type defines http methods associated links (the exception being forms, allows representation specify method restricted set). stand on shoulders of giants.