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.