recommendations regarding resource uri

Question

lets say we have a "door api" and I want to create a resource to close the door.

I could do this in 3 ways:

1. traditional way using PUT with payload {id: XX, color: YY, closed: true}
   • advantages: simple and follows standard
   • disadvantages: client needs to edit the door instance by editing closed property and send the value to the backend. If request fails then client needs to restore value to original.
2. traditional way using PATCH with payload {closed: true}
   • advantage: simple and reduces payload to the minimum
   • disadvantages: same as PUT
3. create a resource /door/close-door/{door id} with PUT?
   • advantages: client code is simple, just call resource and only need to change door object on client if request is successful
   • disadvantages: I am not sure whether this is the right way to create a resource URI

QUESTION 1: could someone please help me to understand any disadvantage of option 3 (which is my favourite one) and if any issue with that URI?

QUESTION 2: I guess I should use PUT verb on option 3... does it makes sense to have PUT without payload?

thanks

Answer 1

Part of the point of REST is that the clients are insulated from the implementation details.

Put another way - you shouldn't be able to tell whether the door is really just a document, or a collection of sensors and actuators.

QUESTION: could someone please help me to understand any disadvantage of option 3 (which is my favourite one) and if any issue with that URI?

There's nothing wrong with the URI -- rest doesn't care what spellings you use for your identifiers.

It does care, somewhat, when you use different identifiers; as far as HTTP is concerned, different identifiers are different, which means that there is no interaction between them in the cache.

That is, if I cache the response to

GET /door/12345

Then successful unsafe methods with that request target invalidate the representation I have in the cache -- that's part of what it means to be unsafe. See Hypertext Transfer Protocol (HTTP/1.1): Caching, Invalidation (section 4.4).

So

PUT /door/12345
PATCH /door/12345
POST /door/12345

will all invalidate the previously cached result.

POST /door/12345/close-door
POST /door/close-door/12345
PUT  /door/close-door/12345

These requests will not invalidate the previous representation, because the request target is not the same.

does it makes sense to have PUT without payload?

There's nothing wrong with that.