4 ms·

Why is POST /accounts/4402278/close correct in the first example? According to the rest of the post, PUT should be a better option. Closing an account seems to

by mikio 10y ago

Why is POST /accounts/4402278/close correct in the first example? According to the rest of the post, PUT should be a better option. Closing an account seems to me like its updating a resource, not creating one. Also, will calling that url close the account multiple times? POST is not supposed to be idempotent

binarymax 10y ago
Or, if you really want to be dogmatic, use DELETE when destroying something...in this case the customer account.
- arethuza 10y ago
  I don't think I would assume that "close" is the same as a delete.
  - 72deluxe 10y ago
    Then why not cater for your own verb instead?
    - caseysoftware 10y ago
      Because you should never, never, never create your own verbs. The main reason APIs have become ubiquitous is that we have a shared understanding that follows us from API to API. That includes the concept of verbs, response codes, and how to interact with the nouns/resources. If you add verbs, you're breaking that agreement. Also, from a technical perspective, some of the internet infrastructure - servers, routers, etc - drop things they don't recognize. Heroku for years was dropping the PATCH verb despite recommending its use for customers' APIs.. and PATCH is in one of the specifications! Imagine what would happen to your custom verb. Don't create your own. Stick to the standards.
- zeveb 10y ago
  Closing it may not delete it, but simply mark it as closed.
  - binarymax 10y ago
    In CRUD, delete is rarely a hard delete that removes the data entirely. Best practice in most situations is setting a flag to mark it deleted. Closing an account is the same behavior - you are not purging the data, rather setting it to a closed/deleted/archived state.
    - caseysoftware 10y ago
      You're packing a lot of implied behavior - based on your experiences - into the DELETE verb instead of using the dictionary definition. If everyone has experience with similar systems, then you're fine. If others have worked with hard delete systems or aren't native English speakers, you're introducing ambiguity and context that isn't necessarily there.
      - binarymax 10y ago
        Using DELETE this way is absolutely not introducing or implying anything, this is best-practice REST. It signifies exactly the behavior I describe.
      - pc86 10y ago
        DELETE simply means subsequent calls to GET should not return that object. So you can call DELETE on an account then your next GET returns a 404 because you deleted it from the database, or you can call DELETE and your next GET returns a 405 because the account has been closed and you're not allowed to call GET on a closed account. Both are totally within the spirit of what DELETE is supposed to accomplish, and I'm sure there are a half dozen other ways to architect it completely within the spirit of DELETE and REST as well.
paullth 10y ago
Maybe there is a closed account sub-resource? :)
zeveb 10y ago
You could PUT the entire value of the resource representing account 4402278 (to include owner's name, contact information, history, &c. &c. &c., or you could PUT a custom range to just update the account status, or you could POST just the update. Honestly, if custom ranges worked a bit better, that'd probably be the best option. Given that they don't, really, I think POST isn't terrible. At least it's not GET!
tremon 10y ago
Because the action is designed to affect the /accounts/4402278 resource. Requiring a PUT here would (semantically) imply that /accounts/4402278 is a container that has various sub-resources. Also, there is nothing wrong with having an idempotent POST effect. "POST is not supposed to be idempotent" is not the same as "POST should never be idempotent". In this case, the POST acts on a boolean flag; it is harder to make it not idempotent.
- drostie 10y ago
  I mean, we're running up against one of the problems which metadata systems have to deal with, which is that metadata about an object really "lives" in parallel with that object, and not really "contained within it". But usually you just think of an object as containing all of the metadata we know about it so far, and under that model this makes perfect sense. To do this in 100% RESTful style you would therefore probably store details about how an account was closed in the /accounts/440278/closed reference, so a PUT is correct, with GET /accounts/440278/closed returning either a 404 for accounts which are not closed or else the metadata about how the account was closed. This could live in parallel with a cache that's on the resource itself describing whether it was closed or not. So, POST or PUT, with the PUT exposing more of the metadata interface to REST and POST putting more of it in the request bodies themselves.
mcherm 10y ago
You may be operating under the misapprehension that "POST" means "CREATE". It WOULD make a nice set with CRUD operations: POST - Create GET - Read PUT - Update DELETE - Delete But that's not actually how the HTTP verbs are defined[1]. Instead, my own mental mapping looks something like this: GET - read information. Must be idempotent and side-effect free so this one really IS just for reading. DELETE- delete. Usually pretty obvious except for arguments about whether a "soft delete" (mark as deleted but don't remove from the underlying DB -- like a bank account which can be closed but continues to exist (its account number, for instance, is never freed up). PUT - update things. Must be idempotent. If you're a stickler for doing things right, this should NOT be use for a "partial update" (where you supply a few fields and everything else is left "as is") but only for a "total update" (where the new thing you sent in replaces whatever was there). POST - "do it". Means to do the obvious thing (whatever that is for this URL). PATCH - great idea. Maybe in a few years support for it will be ubiquitous enough that we can actually start using it. If we DID us it, this would be the partial update variant of PUT. OPTIONS and HEAD - occasionally used at a framework level. You won't ever use it. everything else - don't use it. [1] - https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
- softawre 10y ago
  What doesn't support PATCH these days? I've been using it for many years with no problems.
- drostie 10y ago
  I like to think of DELETE as "if the response to the DELETE is 200-level then further GETs to the resource should be at the 400-level." Call those responses to GET requests "2XXing" and "4XXing" respectively. Similarly a PUT should make sense whether the underlying resource 4XXes or 2XXes, and should in either case make it 2XX with the same response. Then POST is just a verb which does not share these semantics at all; POST <url> can be done on a URL which either 4XXes or 2XXes, and even if the post succeeds that's no guarantee that the underlying URL will now exist. POST /update-caches for example might not change the HTTP statuses of anything.
  - 10y ago

by mikio 10y ago

binarymax 10y ago

Or, if you really want to be dogmatic, use DELETE when destroying something...in this case the customer account.

arethuza 10y ago
I don't think I would assume that "close" is the same as a delete.
- 72deluxe 10y ago
  Then why not cater for your own verb instead?
  - caseysoftware 10y ago
    Because you should never, never, never create your own verbs. The main reason APIs have become ubiquitous is that we have a shared understanding that follows us from API to API. That includes the concept of verbs, response codes, and how to interact with the nouns/resources. If you add verbs, you're breaking that agreement. Also, from a technical perspective, some of the internet infrastructure - servers, routers, etc - drop things they don't recognize. Heroku for years was dropping the PATCH verb despite recommending its use for customers' APIs.. and PATCH is in one of the specifications! Imagine what would happen to your custom verb. Don't create your own. Stick to the standards.
zeveb 10y ago
Closing it may not delete it, but simply mark it as closed.
- binarymax 10y ago
  In CRUD, delete is rarely a hard delete that removes the data entirely. Best practice in most situations is setting a flag to mark it deleted. Closing an account is the same behavior - you are not purging the data, rather setting it to a closed/deleted/archived state.
  - caseysoftware 10y ago
    You're packing a lot of implied behavior - based on your experiences - into the DELETE verb instead of using the dictionary definition. If everyone has experience with similar systems, then you're fine. If others have worked with hard delete systems or aren't native English speakers, you're introducing ambiguity and context that isn't necessarily there.
    - binarymax 10y ago
      Using DELETE this way is absolutely not introducing or implying anything, this is best-practice REST. It signifies exactly the behavior I describe.
    - pc86 10y ago
      DELETE simply means subsequent calls to GET should not return that object. So you can call DELETE on an account then your next GET returns a 404 because you deleted it from the database, or you can call DELETE and your next GET returns a 405 because the account has been closed and you're not allowed to call GET on a closed account. Both are totally within the spirit of what DELETE is supposed to accomplish, and I'm sure there are a half dozen other ways to architect it completely within the spirit of DELETE and REST as well.

paullth 10y ago

Maybe there is a closed account sub-resource? :)

zeveb 10y ago

You could PUT the entire value of the resource representing account 4402278 (to include owner's name, contact information, history, &c. &c. &c., or you could PUT a custom range to just update the account status, or you could POST just the update. Honestly, if custom ranges worked a bit better, that'd probably be the best option. Given that they don't, really, I think POST isn't terrible. At least it's not GET!

tremon 10y ago

Because the action is designed to affect the /accounts/4402278 resource. Requiring a PUT here would (semantically) imply that /accounts/4402278 is a container that has various sub-resources. Also, there is nothing wrong with having an idempotent POST effect. "POST is not supposed to be idempotent" is not the same as "POST should never be idempotent". In this case, the POST acts on a boolean flag; it is harder to make it not idempotent.

drostie 10y ago
I mean, we're running up against one of the problems which metadata systems have to deal with, which is that metadata about an object really "lives" in parallel with that object, and not really "contained within it". But usually you just think of an object as containing all of the metadata we know about it so far, and under that model this makes perfect sense. To do this in 100% RESTful style you would therefore probably store details about how an account was closed in the /accounts/440278/closed reference, so a PUT is correct, with GET /accounts/440278/closed returning either a 404 for accounts which are not closed or else the metadata about how the account was closed. This could live in parallel with a cache that's on the resource itself describing whether it was closed or not. So, POST or PUT, with the PUT exposing more of the metadata interface to REST and POST putting more of it in the request bodies themselves.

mcherm 10y ago

You may be operating under the misapprehension that "POST" means "CREATE". It WOULD make a nice set with CRUD operations: POST - Create GET - Read PUT - Update DELETE - Delete But that's not actually how the HTTP verbs are defined[1]. Instead, my own mental mapping looks something like this: GET - read information. Must be idempotent and side-effect free so this one really IS just for reading. DELETE- delete. Usually pretty obvious except for arguments about whether a "soft delete" (mark as deleted but don't remove from the underlying DB -- like a bank account which can be closed but continues to exist (its account number, for instance, is never freed up). PUT - update things. Must be idempotent. If you're a stickler for doing things right, this should NOT be use for a "partial update" (where you supply a few fields and everything else is left "as is") but only for a "total update" (where the new thing you sent in replaces whatever was there). POST - "do it". Means to do the obvious thing (whatever that is for this URL). PATCH - great idea. Maybe in a few years support for it will be ubiquitous enough that we can actually start using it. If we DID us it, this would be the partial update variant of PUT. OPTIONS and HEAD - occasionally used at a framework level. You won't ever use it. everything else - don't use it. [1] - https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

softawre 10y ago
What doesn't support PATCH these days? I've been using it for many years with no problems.
drostie 10y ago
I like to think of DELETE as "if the response to the DELETE is 200-level then further GETs to the resource should be at the 400-level." Call those responses to GET requests "2XXing" and "4XXing" respectively. Similarly a PUT should make sense whether the underlying resource 4XXes or 2XXes, and should in either case make it 2XX with the same response. Then POST is just a verb which does not share these semantics at all; POST <url> can be done on a URL which either 4XXes or 2XXes, and even if the post succeeds that's no guarantee that the underlying URL will now exist. POST /update-caches for example might not change the HTTP statuses of anything.
- 10y ago