Insomnia: Use API Blueprint for Designer instead of OpenAPI

[ryanprior]

The vision that Designer lays out of an integrated, human friendly workbench for designing and iterating on APIs is poorly paired with OpenAPI, which while being super easy to parse, doesn't really lend itself to a friendly authorship user experience. A great fit would be API Blueprint, which extends Markdown with API description super powers.

API Blueprint files already look like API docs, and there are tools to convert between API Blueprint and OpenAPI for people who ultimately need one or the other for their downstream use case. But in terms of the authorship experience, API Blueprint really outshines the competition with simple plain-text representation that doesn't rely on nested structures and memorizing magic keywords.

[gschier]

Thanks for the suggestion on API Blueprint!

We'd love to support for more API Specification formats in the future, but chose to launch with OpenAPI because it's the most popular amongst the companies and developers we talked to. Do you have any API Blueprint editors/tools that you like already? I'd be curious to see what the ecosystem is like.

💜

[kroleg]

I personally prefer OpenAPI over API Blueprint for many reasons. API Blueprint can be one of supported formats but Designer should not use API Blueprint _instead_ of OpenAPI.

[rmharrison]

@gschier : Do you have any API Blueprint editors/tools that you like already?
Apiary's SaaS "Editor" is more or less the only game in town.

They've open-sourced the parser (drafter.js) and a node wrapper for the parser (protagonist), but the "Editor" proper is closed. API Blueprint is very human readable compared to Swagger, so not having a dedicated editor doesn't become an issue immediately.

Agreed with @kroleg
"Instead of", absolutely not. My roadmap would be:

• import API Blueprint
• export API Blueprint
• edit in API Blueprint (plugin or option for power users)

All low priority because there are already Blueprint to Swagger converters [open-source, closed-source]. It'd also be fair to make an executive decision as Swagger-only.

[ryanprior]

Apart from Apiary, the best API Blueprint editor is Emacs with apib-mode. So that makes this a wide open field for Insomnia to take the best-in-class trophy. Meanwhile there's already a ton of samey box-ticking OpenAPI GUI editors.

I definitely see where people who say "why not both" are coming from, but the user experience is important and in my mind there's no comparison. The priority ought to be API Blueprint because the authoring experience is that much better. It looks and handles like a document instead of a big pile of YAML; it feels like it's meant to be read and used by humans, which is the same vibe as Insomnia in general.

Insomnia and API Blueprint is a peanut butter and jelly sandwich.
Insomnia and OpenAPI is a peanut butter and [hierarchical yaml structure of 45 bland ingredients and fillers] sandwich.

[nijikokun]

I definitely see where people who say "why not both" are coming from, but the user experience is important and in my mind there's no comparison.

We do have plans on our roadmap to support AsyncAPI as well which, pushes us into the "How do we support multiple types - and well".

Current thoughts are to abstract functionality into plugin bundles, that detect type and augment ui and workflows accordingly, thoughts?

[ryanprior]

If multiple types support is already a given, then having that sort of detection to automatically find and use the right bundle would be a solid experience.