An honest review of Insomnia Designer and Insomnia Core
Incremental improvements on your API design workflow
On 28 April 2020, Kong announced Insomnia Designer, a stand-alone desktop application for API design and debugging with native support for Linux, OS X and Windows. This article is a point-by-point overview of Insomnia Designer vs swagger-editor (stand-alone API design) and Insomnia Core vs Postman API client (stand-alone request/response), intended for developers.
Insomnia Designer vs Swagger-Editor
TL;DR: Insomnia Designer is an incremental improvement with potential. I plan to use it on my next project.
Design: Tie
If you’re used to swagger-editor, then you’ll feel right at home in Insomnia Designer. The only major stylistic difference is the left-hand navigation pane, which seems “inspired” by SwaggerHub API designer (SmartBear’s SaaS solution).
Like swagger-editor, the preview pane is a static render and not true WYSIWY. All edits must be applied in the edit pane. This design is straight-forward, but it forces a navigate → edit → preview flow that gets unwieldy in large document. Indeed, if you try and click on a subsection in the preview (intuitive), you don’t snap to that location in edit or navigation. The edit update is also a little sluggish on the preview re-render, but I’m pretty sure that’s Electron and not Insomnia Designer proper.
Developer ergonomics: Insomnia because of Environments
With swagger-editor, you get one environment, the host et al. you include in your swagger doc. These will have to be changed and changed back each time you export, lest you commit configuration that should be private.
Insomnia allows you to keep config private in environments, including ENV not included in the swagger spec, AND easily toggle between any public or private environment. I loved this feature.
Import / Export: Tie
Realistically, you’ll be using Swagger v2 or OAS v3 with either of these tools. Moot point.
Collaboration: Insomnia because GitSync could be a game changer for small team workflow
Same features as swagger-editor, with slight refinements to developer ergonomics. You might be thinking, why bother.
The innocent looking “Setup Git Sync” button nestled in the upper-right hand corner of the client. This button could improve your small team workflow. With it, you can push/pull directly to your git provider of choice (I tested on GitHub). The documentation needs work for onboarding, but the functionality works and I expect the gotchas will be resolved in beta:
- Imperative that you work on different branches because Insomnia will explode on merge conflicts
- Directories must be empty, so you can’t host the spec alongside your code and other documentation in the same repo.
When the kinks are worked out, I expect GitSync to be a game changer for the workflows of small teams.
On the contrary, swagger-editor offers no collaboration; you’d have to execute the pull/commit/push follow outside of the tool. In my experience, more than 2 developers pairing on a swagger-editor file is a recipe for chaos.
Integration: swagger-editor because of the built-in swagger-codegen support
While client and server generation support is available from the swagger-editor UI, the functionality is derived from swagger-codegen.
Because the API contract development I’ve done has been so iterative, I haven’t found much use for the server generation. The server export doesn’t automagically apply diffs, meaning in practice it’s only useful the first time.
The client SDK export on the other hand is a gem. You can create a so-so client from any contract. Human curated SDKs will have better ergonomics that account for the vagaries in common use of a given language; but, this will get you a client in minutes rather than days.
Yes, swagger-editor “wins” the category; but, Insomnia doesn’t need this integration. Use swagger-codegen for client SDK generation as apart of your build pipeline.
Licensing: Tie
Swagger-editor’s Apache 2.0 vs Insomnia’s Expat (AKA MIT) license. Both permissive. Both open.
Community support: swagger-editor
Say what you will about SmartBear, they have supported a vibrant open-source community around Swagger (now OpenAPI spec) for a decade. Swagger is the de facto standard in API specification, unless you’re really into top-down (Mulesoft RAML) or really into documentation that can moonlight as a contract² (Apiary API Blueprint). That Swagger is just Swagger, is a testament to the community. A community that, to it’s credit, SmartBear stewarded into the Linux Foundation and did not destroy. They could have Oracle’d and deliberately fractured the community (never forget). But they didn’t.
Aside on SaaS tools: Apiary and SwaggerHub
As SaaS-only tools, Apiary (Oracle) and SwaggerHub (SmartBear) are not directly comparable to stand-alone clients such as swagger-editor and Insomnia Designer. A comparison of these tools to Insomnia would be a Latke-Hamantash of SaaS-Desktop.³
Apiary forces you to integrate with github (but not other git providers, which the access_token approach of Insomnia allows), forces you to use Apiary team settings and forces you into their SaaS platform editor which only allows editing in Apiary API Blueprint.
SwaggerHub is worse in that it forces you to house your specs on their platform, which forces all collaboration into their SaaS.
Apiary and SwaggerHub are fine solutions, for Enterprises. I admire the elegance of API Blueprint for human-readable documentation that moonlights as an API contract (also useful for non-Enterprise), and have used it on non-personal projects.
Insomnia Core vs Postman
TL;DR
- Advanced users, stick with Postman because of newman-cli.
- New users, get started with Insomnia Core because it’s more intuitive.
- Respects your freedom, Insomnia is a much lesser evils.
Design and developer ergonomics: Insomnia
The re-brand from Insomnia REST is justified given the expanded support for GraphQL. This isn’t just marketing speak. Imagine Postman with a much cleaner interface, including intuitive keybindings. The screenshots of the OAuth2.0 Authorization code preset say it all.
Integration: Postman, because of newman-cli, but this only applies to advanced users.
Yes, Insomnia Core wins the design contest; but, for advanced users of Postman, I don’t feel a compelling reason to switch. Postman is an excellent tool, made more excellent by the newman cli, which has no equivalent (that I’m aware of)⁵ in the Insomnia community.
If you’re deciding on your first API client, I’d give Insomnia Core a try. It’s clean interface is intuitive. Unlike Postman, you won’t have to google to figure out how to perform a basic action like update headers. cluttered interface has a steeper learning curve than is neccisary to graphically hit a few end-points because tracking changes to curl commands through your history is annoying.
Import: Tie
The import for Insomnia and Postman are broadly comparable. Postman does not support HAR imports. Insomnia supports Postman, but Postman doesn’t support Insomnia. Otherwise they both support your usual names, mostly importantly Swagger (OpenAPI Spec).
Unless you happen to need RAML imports and a RAML-to-Swagger converter won’t do, they’re equivalent. Neither support imports from API Blueprint (Apiary), so Apiary users must export (most likely to Swagger/OpenAPI) for compatibility.
# Import comparison of Insomnia Core and Postman
| Insomnia-only | Both | Postman-only |
|-----------------|----------------|-----------------|
| Insomnia | Swagger (v2) | RAML |
| HAR | OpenAPI (v3) | Runscope |
| | Postman v2 | Postman v1 |
| | WADL | |
| | cURL | |Export: Insomnia, shame on Postman.
Postman’s lack of export functionality is a callous disregard for developers. Insomnia supports their own format and HAR (an emerging W3C standard). You can also select which requests to export, while Postman is all or nothing. A direct Insomnia JSON export and Postman Collection v2 (import) → HAR (export) worked seamlessly.
Postman only exports to Postman. HAR import support has been on Postman’s backlog for 7 years!? without movement. They say if you want it bad enough fix it yourself, but I can’t because Postman doesn’t respect my freedom and is closed-source. The lack of import/export to an open format like HAR means that Postman is not interoperable.
# Export comparison of Insomnia Core and Postman
| Insomnia-only | Both | Postman-only |
|-----------------|---------|---------------|
| Insomnia | | Postman |
| HAR | | |Collaboration: Tie
Using “Share Workspace” (Insomnia Core) and “My Workspace” (Postman) require their SaaS offering. Another account, another silo. Postman offers Google sign-in. Apiary offers Github and Twitter!? (Oracle salesman). None offer GitHub, GitLab or Bitbucket for individuals. Presumably Insomnia SaaS allows SSO for their enterprise tier, so I’d class this as one of those little cuts that hurts trial.
Licensing: Insomnia, but they failed to use the release of a new tool to use AGPLv3 instead of Expat.
The Postman desktop client is closed source. Automatic fail. They allow support issues on github. We’re developers, which means the “open dialogue” and “transparent roadmaps” mentioned on their “Open Philosophy” are not open.
The Insomnia desktop client is open-source under the Expat license (AKA MIT license). The Expat license is permissive, and is often used by open source (as opposed to libre) companies instead of the the GPL/AGPLv3 (strong copyleft, non-permissive). Kong had an opportunity to release under GPL/AGPLv3 and make a public commitment to the four freedoms in their API tooling. They didn’t. Still, an open source Insomnia wouldn’t exist without the foresight of one developer, and would whither and die without developers pushing for open source (and maybe even libre) within Kong.
Wrapping-up
Design decisions
Both Insomnia Designer and Core appear well throughout. All the bells and whistles aren’t there in Insomnia Designer (nor should they be). You can tell Designer is in beta; but more importantly, you can feel the team’s intent.
- Unix philosophy on modularity. Splitting Designer from Core to keep them both light-weight. Unlike Postman, there won’t be some bells and whistles. This avoids the bloat of Postman, at the expense of some integration issues (e.g. you can’t seamlessly reuse Workspaces between the two applications).
- Key-binding forward. They don’t expect you to hit the send button to send a request. They expect
Ctrl+Enter. This is much faster and gives you the feel of a developer-focused tool. - Stand-alone desktop client instead of web-based (Apairy, SwaggerHub). The desktop client is your gateway drug to the SaaS offering. Well played.
Industry context
Over the past few years, the API development ecosystem has been devoured by large incumbents — 3Scale (IBM via Redhat), Apigee (Google), Apiary (Oracle), RAML (Salesforce via Mulesoft). Insomnia (Kong) and SwaggerHub (SmartBear) are minnows, competing against these titans with solid software that works.
The API oligopoly represents a risk to innovation and software freedom, as more and more of our lives are transacted via APIs. Kong has selected an “open-core” business model for Insomnia, monetizing on Enterprise with a (closed source) SaaS offering that meets corporate desire for one throat to choke, security (SSO) and heirarchical control of large teams.
At best, Kong is an open source software company, not a libre software company. As a company, Kong is VC-backed, not a community-centered cooperative. Kong does not not respect your freedom; none the less, the jaded pragmatist asserts that “open-core” is better than closed.
Disclaimer
Ryan’s thoughts/comments are his own.⁴ He has no financial relationship with Kong (the aquirers of Insomnia the company). He writes software for an open-source health data interoperability consultancy, doing “API stuff” when not doing “technical advisory stuff.”
Footnotes
¹ Thanks to James Agnew and HAPI FHIR for maintaining public sandbox servers. Thanks to Athiththan Kathirgamasegaran; since I didn’t want to use Petstore for the billionth time, all of the Swagger used in this article was generated with his FHIR-to-Swagger tool. FHIR (Fast Healthcare Interoperability Resources) is an open standard for health data interoperability.
² “Documentation that can moonlight as a contract” is high praise. I routinely read/write Apaiary API Blueprint in vim. Not happening in Swagger JSON. Swagger YAML, maybe for a couple of end-points. I haven’t used it, but I enjoyed the vim kludge to swagger-ui.
³ If you’re game, I might be convinced to take one side of the debate stand. Maybe.
⁴ Many thanks to the Swagger and Insomnia communities. Ode to FLOSS maintainers.
⁵ insomnia-cli is a 3rd party CLI tool for Insomnia REST (now Insomnia Core). That Insomnia has spawned 3rd party contributions is admirable, but I do not consider it the equivalent of Postman’s 1st party newman-cli because it lacks: adoption, active maintenance, reporters and lifeCycle hooks.
