rest - RESTful APIs when multiple actions on the same URI -

rest - RESTful APIs when multiple actions on the same URI -

so far know, 4 kind of methods used in restful apis:

get getting resource. post updating resource. put creating or substituting resource. delete deleting resource.

assume have resource named apple, , can 'update' in several ways. example, pare it, piece it, or create apple juice. each of these 3 different updating actions takes different arguments, , of apis, mutual part be:

post /apple http/1.1 host: www.example.com <different combination of arguments>

in situation, 3 apis share same uri , same request method, differences of them arguments. think forces backend ready accepting union set of arguments, , distinguish action requested, backend need check out combination of arguments. it's much complicated , not graceful.

so question is: in apple cases, how work out elegant set of restful apis create backend handle it.

first of all, seek avoid conflating http methods crud operations. believe that's main source of confusion in rest. http methods don't translate crud operations cleanly that. have detailed reply here:

s3 rest api , post method

in short.

post method used operation isn't standardized http, , subjects payload target uri. put used replace resource @ nowadays uri, , subjects payload service itself. patch partial idempotent updates, diff between current , desired state. delete used delete resource. get used retrieve resource.

now, on backend side, seek think of rest resources more state machine can utilize methods forcefulness transition rather object methods. way focus implementation on resource itself, not on interaction protocol. instance, may alter object's attributes straightforwardly method's payload, , have method that's called observe transition needed.

for instance, may think of apple having 3 states, whole, pared, sliced , juiced. transition between states using standardized behavior of methods.

for instance:

get /apple {"state": "whole", "self": "/apple"}

then want piece it. may like:

put /apple {"state": "sliced"}

or may like:

patch /apple {"from_state": "whole", "to_state": "sliced"}

or like:

post /apple {"transition": "slice"}

the thought implementations can generic plenty don't have worry much coupling resource http methods.

the set version idempotent, clients can take utilize when need idempotence. the patch version guarantees client knows current state , trying valid transition. the post version flexible, can want, needs documented in detail. can't assume clients know how method works.

as long implementation of resource understands when apple.state changed else should observe alter occurred , perform adequate transition, decoupled protocol. doesn't matter method used.

i believe elegant solution, , makes easier handle backend side. can implement objects without worrying much protocol. long objects can transitioned between states, can used protocol can effect transitions.

api rest