api - Idempotent PUT in a concurrent environment -

context

i have rest api multiple clients (applications) can update state of resource put. example, resource lamp can turn on or off.

this resource automatically updated system when detects electricity failure has occurs, leading have lamp in broken state. want made distinction between broken , off, lamp in broken can not turn on !

problem

i use put method this, put http://address:port/my_lamp { "state": "on"}

but not sure if respect idempotent property of put method. in fact, have 3 cases:

• the lamp on. above code leads on state.
• the lamp on. above code leads on state.... cool! @ moment, idempotency still guaranteed :-) !
• the lamp broken. above code leads error, 503 service unavailable

question

i not sure correctly understand notion of idempotency. trust me, read lot of thing still little bit confused.

in understanding, multiple put leads same state of resource: not guaranteed in case due broken

but understand in other way: multiple put leads same side-effect: guaranteed, request either produce turn on, either nothing (for broken case, in).

edit:

mean: side-effect turn on lamp, guaranteed (it either turn-on or nothing here)

see here: is rest delete idempotent?

which 1 correct ? depending of understanding, rest api ensure idempotency or not...

edit2:

definition of w3c

methods can have property of "idempotence" in (aside error or expiration issues) side-effects of n > 0 identical requests same single request.

can consider it's error turn on lamp when broken ?

idempotency means in isolated environment multiple requests same client not have effect on state of resource. if request client changes state of resource, not break idempotency principle. although, if want ensure put request not end overriding changes simultaneous request different client, should use etags. elaborate, put request should supply etag (it got request) of last resource state, , if etag latest resource should updated, otherwise 412 (precondition failed) status code should raised. in case of 412, client suppose resource again, , try update. according rest, vital prevent race conditions.

to elaborate more:-

according w3c(http://www.w3.org/protocols/rfc2616/rfc2616-sec9.html), 'methods can have property of "idempotence" in (aside error or expiration issues) side-effects of n > 0 identical requests same single request.'

get request - {'state': 'on'} etag-header(say)- 123 put request - {'state': 'off'} etag-header - 123

some internal activity changes state such new state {'state': 'broken'}. in etag should changed 124.

put request - {'state': 'on'} etag-header - 123. since etag header has changed, 412 error returned not break idempotence of api (aside error or expiration issues).

get request - {'state': 'broken'} etag-header - 124 put request - {'state': 'on'} etag-header - 124