← Back to context

Comment by onion2k

7 years ago

Exactly. A 'toggle' should really be implemented as a PATCH request, or maybe a PUT if there's no data other than the door state.

17 comments

onion2k

Reply
hardwaresofton  7 years ago

At the risk of being overly pedantic/piling on -- this is what bad REST-ful API design looks like in practice.

When you talk to your teammates about the semantics of these verbs and someone just says "oh a GET is fine" and the team agrees but you don't and you can't say it so you don't become "that guy" it's time to find a new engineering org to be a part of.

On the topic of PATCH, check out JSON merge patches (application/merge-patch+json):

https://tools.ietf.org/html/rfc7386

  • Senderman  7 years ago

    I hope this doesn't come across as mean-spirited, but I'm really struck by the middle part of your comment, even though I think it was meant as a throwaway remark.

    It sounds like you're advocating leaving an organisation instead of speaking up when a mistake is being made? In the scenario you described, the "a GET is fine" person is unfamiliar with the protocol they're writing for (HTTP), and so is every person who agreed. Leaving instead of speaking up seems pretty drastic.

    • hardwaresofton  7 years ago

      Totally valid question -- it was indeed a throwaway remark but is pretty bitter in tone now that I think about it.

      To delve into what I was thinking a little bit I think it came off so bitter because I've been in too many orgs where group-thinking squashed dissenting possibly-correct opinions, where half the room is wondering "this seems too complex, why are we doing this" but everyone goes with it. Reading through the twitter comments had a bunch of people were trying to gloss over the misuse and it might have triggered me.

      The more reasonable response is definitely to articulate and explain why a GET is NOT fine in that case so everyone learns, but once this starts happening a lot I mark it as a red flag in my head -- it's either a culture clash or I'm too close to being the most experienced in the room (in that specific area), and that means there are less people to learn from and staying for too long might lead to stagnating. The "leave the org" bit is hyperbole, but I worry about this kind of thing if I experience it.

      In the end though, it was meant to be a humorous post so the remark is overblown.

    • samb1729  7 years ago

      My interpretation is that GP is advocating leaving an org if you feel that speaking up is discouraged

  • strictnein  7 years ago

    Hadn't seen that RFC before. We were doing almost exactly that on a large API project a year or so before that RFC was published. Backend guys hated it, front end guys loved it.

mvindahl  7 years ago

Absolutely agree. A PUT method carrying an open/closed flag would seem like a natural choice. Calling it any number of consecutive times with the same payload would be idempotent. There would probably be a GET method to go along with it. And of course, it would model the desired state, not the actual position of the garage door since garage doors don't instantaneously flip (would be cool though).

dragonwriter  7 years ago

A toggle would actually be a good use of POST, though PUTting the desired state would be better (PATCH works instead of PUT if you are changing some part of the state and not the whole state, but is unnecessary if the door state consists entirely of either “open” or ”closed”.)