I’m working on a new application. I got the basics done, and because I’m an old crank, I made the data storage a file. So, you can do all kinds of cool things with the data you enter, and you can do it without having a network connection. It’s like a spreadsheet!
But then, my target user said, “I really want to be able to collaborate with other people on this. It shouldn’t be a document, it should be a web service.”
“This time,” I thought, “I’m going to be smart and actually design the API before I just bang something together!” Isn’t it cute, how I’m all optimistic like that?
Anyway, I looked around and found that nowadays all the cool kids are using OpenAPIs to define their services. It also turns out that Insomnia understands openapi, so I can document the API in one editor pane and then in the next tab over I’ve got request stubs already defined for all the endpoints. That’s actually pretty cool!
But, as usual, it’s never all good news. For starters, the openapi definition is either JSON or YAML. Gross. But at least the editor lets you collapse sections, so it’s relatively tidy. But, and this isn’t just Insomnia, it’s everything that manipulates openapi stuff: the parsing of the definition is done by swagger, which doesn’t understand openapi version 3.1 (which was released last year). Not that I actually care all that much, since I’m not intending to use any features introduced there — 3.0 is good enough for now. Still, it’s an irritant.
Also, Insomnia doesn’t let you save the definition to the local filesystem. If you want to save the definition somewhere, you can hook up git and push your definition to some repository somewhere, or you can just copy and paste it from Insomnia into SubEthaEdit or whatever.
Oh, and the other irritant that got me to start writing this post in the first place: syntactically significant indentation, and a domain-specific editor that doesn’t show you the indentation level or make it easier to be at the right indentation than at the wrong one! Seriously, I feel like the guys who developed YAML were probably Python programmers.
You would prefer XML?
Also, if your editor sucks at YAML, time for a plugin or a new editor!
No, in this case I would not prefer XML. And let me just start out with, good graphical text editors are hard to write. Syntax coloring, formatting, typeface fiddling — it’s all a heck of a lot of record keeping and at the end of a week’s hard thinking and careful tweaking, I still wind up with a buggy piece of crap that looks terrible. So it is a miracle that there exist any half-decent editors at all, and I’m grateful for the people who build them. That said, I just spent half a day looking specifically at YAML editors and THEY ALL SUCK. None of them address the problems I have with YAML, and that’s actually a miracle because I don’t imagine that I’m all that special; there must be other people who are similarly troubled.
Meh. VS Code with the usual YAML support.
It is interesting how I’m coming across more and more programmers who don’t like the indentation style of python.
Not that I have any problems with it, since I’m not a huge fan of it myself.
“Meh” indeed. Fundamentally, YAML is not a human-facing format. It’s not *for* humans; it’s for code. So the right thing is not a good YAML editor, it’s a domain-specific editor that deals in domain entities and properties, and just outputs YAML that can be sent to whatever code wants to import it.
I guess I disagree with that in the same way that any computer language isn’t for humans. Doesn’t mean we should not have a solid editor for ’em.
Concrete example: lots of configuration files for rails (or other) frameworks use YAML. This includes the localization files. They are clearly meant to be edited/maintained by humans – for computers.
I think the use case of a computer generated YAML document for storage is relatively unusual.
https://yaml.org/
What It Is:
YAML is a human-friendly data serialization language for all programming languages.
If I make a website that claims that HTML is for humans, does that make it true? Just because it’s a plain text format that can be read and modified by vi, does that mean we shouldn’t have editors that don’t suck? I think it’s plain that there’s a difference between *can* and *should*. The fact that YAML is omnipresent as a configuration definition format just tells me that there are lots and lots of programmers who are putting up with user-abusive editors.