Incrementing or decrementing a counter is neither side-effect-free nor idempotent, and GET should generally be both, so you really shouldn't use GET for those operations. [1]
POST would probably be the usual choice for these operations. (Though, since you aren't really creating a subresource but are instead performing a defined transformation on an existing resource, you could probably make a case for PATCH.)
Web APIs are protocols implemented on top of HTTP, and should respect the semantics of HTTP unless there is a clearly-identified compelling reason not to.
Yeah, ok. I agree with that. I changed incrementing and decrementing operations to POST requests only, and updated the documentation. Thanks for the feedback!
I believe most anayltics platforms use/support GET, e.g. google analytics, mixpanel etc. If you limit yourself to use only POST, you will limit users from using your tool in areas like email pixel tracking where only GET is allowed.
Doing a cross domain POST is a pain. Doing a cross domain GET is what you do everyday. If you want to increment a counter based on a user action on a web page, then a GET makes a lot of sense.
Yeah, see I'm kind of torn, because GET just makes it so dang simple. POST requests, though semantically correct, add a small amount of overhead to implementing the counter. I'm not really concerned with spiders, as the URLs are intended to be obscure + robots.txt. In addition, future versions could include simple basic auth for private URLs. Though I intend to keep public URLs around for fun and drive by counting.
Yes ... And to address one of the comments above, PATCH is used to merge data into an existing record while PUT is used to replace the existing contents. This is a bit of an odd case since you wouldn't be sending data in either case.
Web crawlers and web page views index using GET; if GET affects your server state, so do page views and indexing.
GET is idempotent. That's not outdated, and it's not arbitrary: it is literally stated in the protocol specification. It's a useful distinction created and used by professionals to maintain sanity in complex schemes of communication.
Please do not ignore technical details because you think you're smarter than everyone else on the planet, or that the problems they solved a decade ago somehow went away in the face of node.js.
edit: Just in case you (or anyone reading this) is unaware of it,
Naturally, it is not possible to ensure that the server does not generate side-effects as a result of performing a GET request; in fact, some dynamic resources consider that a feature. The important distinction here is that the user did not request the side-effects, so therefore cannot be held accountable for them.
I think that, depending on what his API is trying to do, GETing a counter URL to increment it could be acceptable if his service's main purpose is to be accessible via client-side javascript.
That being said, once you go down that road you have to begin taking into account everything that may depend on GET idempotence: send back proper caching headers as well as busting caches from the client side, decide whether or not you want to block javascript-parsing web crawlers, etc.
Because they are going to be used in an environment where there are lots of other things built based on the specifications and which are likely to rely on (or, in some cases, have inspired) the semantics described in the HTTP spec -- including lots of the infrastructure of the web.
Those were arbitrary and out dated.
There may be some issues with them, but those would fall under the umbrella of "clearly-identified compelling reasons".
Comments
Incrementing or decrementing a counter is neither side-effect-free nor idempotent, and GET should generally be both, so you really shouldn't use GET for those operations. [1]
POST would probably be the usual choice for these operations. (Though, since you aren't really creating a subresource but are instead performing a defined transformation on an existing resource, you could probably make a case for PATCH.)
Web APIs are protocols implemented on top of HTTP, and should respect the semantics of HTTP unless there is a clearly-identified compelling reason not to.
[1] http://tools.ietf.org/html/rfc2616#section-9.1
Yeah, ok. I agree with that. I changed incrementing and decrementing operations to POST requests only, and updated the documentation. Thanks for the feedback!
I believe most anayltics platforms use/support GET, e.g. google analytics, mixpanel etc. If you limit yourself to use only POST, you will limit users from using your tool in areas like email pixel tracking where only GET is allowed.
Doing a cross domain POST is a pain. Doing a cross domain GET is what you do everyday. If you want to increment a counter based on a user action on a web page, then a GET makes a lot of sense.
Yeah, see I'm kind of torn, because GET just makes it so dang simple. POST requests, though semantically correct, add a small amount of overhead to implementing the counter. I'm not really concerned with spiders, as the URLs are intended to be obscure + robots.txt. In addition, future versions could include simple basic auth for private URLs. Though I intend to keep public URLs around for fun and drive by counting.
Wouldn't you want to do a POST for creating the first counter and then a PUT for updates?
Yes ... And to address one of the comments above, PATCH is used to merge data into an existing record while PUT is used to replace the existing contents. This is a bit of an odd case since you wouldn't be sending data in either case.
why should they respect the semantics? Those were arbitrary and out dated. I don't see any need for that.
Web crawlers and web page views index using GET; if GET affects your server state, so do page views and indexing.
GET is idempotent. That's not outdated, and it's not arbitrary: it is literally stated in the protocol specification. It's a useful distinction created and used by professionals to maintain sanity in complex schemes of communication.
Please do not ignore technical details because you think you're smarter than everyone else on the planet, or that the problems they solved a decade ago somehow went away in the face of node.js.
edit: Just in case you (or anyone reading this) is unaware of it,
http://www.ietf.org/rfc/rfc2616.txt (or pretty: http://pretty-rfc.herokuapp.com/RFC2616)
Find Section '9.1 Safe and Idempotent Methods'.
Naturally, it is not possible to ensure that the server does not generate side-effects as a result of performing a GET request; in fact, some dynamic resources consider that a feature. The important distinction here is that the user did not request the side-effects, so therefore cannot be held accountable for them.
I think that, depending on what his API is trying to do, GETing a counter URL to increment it could be acceptable if his service's main purpose is to be accessible via client-side javascript.
That being said, once you go down that road you have to begin taking into account everything that may depend on GET idempotence: send back proper caching headers as well as busting caches from the client side, decide whether or not you want to block javascript-parsing web crawlers, etc.
Because they are going to be used in an environment where there are lots of other things built based on the specifications and which are likely to rely on (or, in some cases, have inspired) the semantics described in the HTTP spec -- including lots of the infrastructure of the web.
There may be some issues with them, but those would fall under the umbrella of "clearly-identified compelling reasons".
They were arbitrarily decided a long time ago by people who put much more thought into it than you or I, most likely.
Especially in the case of HTTP/1.1, it wasn't "arbitrary", it was based on quite a bit of experience with HTTP in the wild.
(I don't actually believe near any of these things are "arbitrary"--was being facetious in response to tone of the poster.)