Hacker News Reader

Comment by onion2k | Hacker News Reader

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.

View on HN

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

Just be the guy who says "oh a POST is fine" first

Yeah, full REST is nice, but you can do worse than just using GET and POST as long as GET doesn't change state.

Layers of REST that people get to:

1. GET is good for everything

2. Perhaps we should use POST too

3. Let's use all the verbs

4. Someone mentions HATEOAS

5. Some old guy says that you've got to use XML because that defines links and JSON doesn't

6. Someone else counters with JSON-LD and sends a link to the W3 spec

That's as far as I got. Mostly this conversation happens in my head.

So I'm actually really interested in this conversation -- I think it's a good one that everyone has that needs to just get resolved. I think deciding where to follow and how much to follow REST/HATEOAS is exactly what engineering teams should decide. There are escape hatches (POST can do just about anything) and lots of ways to do things but REST-ful (not pure necessarily pure REST) and HATEOAS-y (usually comes up in terms of pagination/relations first) APIs are not bad at all.

I think JSON+JSON-LD still offers some benefits over XML at the very least in the security sense -- while it can be misused, there are much less dynamic bits built in to the transfer language itself.

Also I'd say that JSON "scales" well in terms of complexity still, small things are cognitively light, and big things are linearly more cognitively heavy.

Is JSON+JSON-LD+X the new XML?

Is Swagger the new WSDL/SOAP?

I dunno, but it doesn't feel like it's quite that bad yet.

SOAP-XML request handling in C on a 100mhz embedded microLinux MMUless processor with plenty of processor and shitty kernel arch bugs ruined my life for a year once.

I mean it's the obvious choice for a simple control UI implementation on a slow embedded system...

You may resume your javascript framework discussion now.

JSON-LD is a significant cognitive leap to reason about [1], and its descriptive power goes beyond what you could do with XML. A JSON-LD document is effectively an RDF document coupled with a JSON document, in a seemingly human-friendly form, although lots of people will recognize the letters but have no clue what they're reading.

For that matter, link relations too are a cognitive leap, and no one writes 'smart REST clients' anyway: these days, to consume a "REST API" you use the first-party official library, or something you found on github, or something you wrote in 3 hours where all the URLs are formed by string concatenation. Within one vendor's one particular REST API, the benefits of HATEOAS are typically minimal, which is why it's so frequently omitted and no one complains except REST pedants.

It also doesn't help that the field still hasn't settled down in ~10 years: JSON Schema, widely used for JSON schemas due to the lack of an official mechanism, recently decided they wanna get into hypermedia too [2], and there's also the enticingly named JSON API, which offers a similar data model too. And let's not forget about stuff ~2011-2013 like HAL [3], which didn't really become big, but never fully went away.

Swagger is absolutely much the new WSDL/SOAP ecosystem, complete with first-party code generators. In the WSDL days, all of your code generators were third-party, and due to enough knobs in WSDL and enough accumulated design baggage, it wasn't always interoperable [4]. But when it was, it was pretty magical for ~2003.

Swagger had clout and name recognition to kill the other schemes that are largely the same, but then they renamed it OpenAPI to play up the consensus against competing codegen/specs like RAML. Now that Mulesoft has agreed to bring RAML under the OpenAPI umbrella, there's less integrated competition, but then OpenAPI's uptake will be limited by those put off by serious tooling who opt for simpler description languages instead. It's a mess.

[1] https://www.w3.org/2013/dwbp/wiki/RDF_AND_JSON-LD_UseCases [2] http://json-schema.org/specification.html [3] http://stateless.co/hal_specification.html [4] https://blogs.msdn.microsoft.com/dotnetinterop/2005/01/17/ne...

I'm not sure it's possible for JSON-LD to go beyond the descriptive power of XML, because XML is so general, flexible and powerful (and you could cretainly represent an RDF document in XML) -- the big upgrade there IMO is that it stays in relatively human-readable form (though depending on the human, so does XML).

Ditto on the huge disappointment with the cobbled together SDKs when HATEOAS/JSON-LD-fluent applications represent a more robust future that could have been the current timeline.

Also, it's a shame that hyper schema couldn't reconcile with JSON-LD. JSON-LD is the one I'm leaning towards using at the moment, because of it's early consideration of things like multiple languages.

It's reassuring (?) to see the mention of the RAML/Swagger situation being a mess from someone else. I actually liked RAML more than the Swagger specification, but Mule (https://en.wikipedia.org/wiki/Mule_(software)) left a bad taste in my mouth once upon a time, when a team I was on was deciding how best to create an ESB. I choose to go with "OpenAPI" (AKA Swagger 3.0) for my projects going forward not for that single personal reason but rather due to the sheer amount of people that have gotten behind Swagger -- they seem to have won the mindshare battle, if not the war.

I have picked a lot of things I thought were cleaner/technologically superior/whatever that lost the mindshare war in my lifetime, I'm trying to cut down.

HAL is personlly my current favourite, it seems to add the minimal overhead on top of JSON whilst adding in links.

> JSON-LD is a significant cognitive leap to reason about

I fully agree. JSON-LD requires first some kind of idea about RDFa which I didn't even know was a thing until reading up on JSON-LD.

I've had to develop APIs for clients that could only do GET or POST requests. Sometimes you have to sacrifice correctness for what's actually possible.

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.

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

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.

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.

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).

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”.)

One more thing: PATCH needs to do atomic updates on a partial resource per http://restcookbook.com/ (which I think is a great TLDR resource on the topic).

Reply on news.ycombinator.com