Show HN: Insomnia Designer – Open-source collaborative editor for API design
insomnia.rest
insomnia.rest
Please don't take Insomnia down that path, and make all enterprise/collab/cloud feature optional while still focusing on the single-user, simple to use and setup program it has been so far.
Users love our products for their simplicity and the streamlined nature and we fully intend to keep that essence going forward.
It is really refreshing to see someone explaining their simple first-principle reasoning on something as controversial as this, and that specific decision working out great for the users.
Far too often we see a major industry player doing something drastic that users dislike (e.g., Postman bloat situation), and the competitors simply following the suit because "our competitors are big and smart, so it must be a good change that we should follow as well".
Sure, the whole cloud login, team synchronization stuff is totally useless for me, but it is not mandatory. Anyway I can understand why it may be frustrating to see all this bloat.
On the other hand I found that Insomnia lacks a few features that Postman has. For example there is no way to do scripting in Insomnia, there only is request chaining which is IMHO way more limiting than the Javascript sandbox that Postman provides. Most notably there is no way to generate request data on the fly.
feel free to email - nijiko@konghq.com
I'm a big Insomnia fan and always recommend it over Postman as it's simple to use. Although even it feel a bit to "modern UI like" to me. I'd really love a old fashioned win 95 UI for this kind of thing. Tortoise git for example is my idea of a nice UI for a tool.
Re xplat: they recently announced a cross-platform beta that will replace the Windows-only one in the long-term; I haven't tried it myself though.
I gave the designer a quick try and it seems there are issues with importing OAS 3/yaml APIs making heavy use of $ref and multiple files, but I will dig deeper into this in the next days and open a bug report if needed.
My team used insomnia for a while. We were on the paid tier. My boss had us bail because of pain points we were having with syncing environments. People were overwriting changes on accident, and it was hard to coordinate.
I like Insomnia more than what we have now, but I wanted to let you know that was the pain point that lost you some customers so you can hopefully address that to avoid losing future customers. :-/
I think something like a "locking" feature or the ability to prevent certain users from modifying certain shared environments would have helped.
We switched to first vscode rest client and now the intellij embedded one at this point, as having the calls saved in clear text makes it possible to just have a request directory directly in the Repository... With transparent reviews etc.
Exporting/importing is just way too troublesome.
I thought I did something cool by taking our existing express routes, generating a boilerplate OpenAPI spec, and then integrating it with our testing suite so the response type-matched the spec... but now I'm reading all this stuff about spec-first approaches to software design and I'm feeling like both my app and I are dinosaurs, and all this is only meant for brand-spanking new software.
But I also don't want to hand-roll my docs by just writing Sphinx. I like the "provide a schema definition then supplement with hand-written docs and customization" approach.
This way the workflow can be specialized for your needs.
One minor bit of copyedit help; on the landing page, near the bottom:
>"most users love it for how simple and easy it is to use. In order to maintain this core tenant..."
tenant (resident) -> tenet (principle)
A lot of APIs in the wild actually do utilize oneOf responses (e.g. for returning rich structured errors that have an enum and a human-readable description but which all share the same HTTP status code) -- I know at least at $DAYJOB this was a major deterrent from using OpenAPI.
Depending on your actual API structure you may be able to generate a complete specification without ever touching any yaml. Been using it for the LinkAce API docs and it helped me a lot: https://stoplight.io/p/docs/gh/kovah/linkace-api-docs
Essentially, Designer helps you design APIs and Core helps you explore them. Depending on what you're doing, you may want to use Designer, Core, or both.
Creating the documentation is a hard, but having developers keep updating it is even harder. And if it's not updated regularly, it loses its value quickly
We do believe in Design First Development, where the idea is designed out with the key party members as a part of that group. In this case, it could be the Lead Architect, or Team Lead, or Individual Contributor starting the specification and working closely in source control / pair programming to define that first draft to prevent things tech debt, refactoring, recoding, etc.
Once it's agree'd upon and merged into the codebase, we believe from there, should you setup a pipeline to have it be updated from the codebase, which commits to the repository, that should be allowed as long as the process is kept. So you still have tests against your specification that ensure your implementation works as described, and your specification is validated and enforced with the right policies.
We have some known gaps around policy enforcement and placement that we intend to correct soon. But, this is our belief.
As far as UI driven design, or Text driven design, I personally believe that both can be achieved. Not everyone knows these specifications and having an interface can on-board those individuals and get them ramped up quickly to service the needs and demands of the business.
Where the text form is useful for advanced users, quick changes, automation pipelines, testing frameworks, diff checking, and so forth. So we don't want to ultimately get rid of that layer either.
I think the best approach will be some form of a balancing act. Would love to hear feedback on this.
I assume it's supposed to have something there based on the screenshots where I can manipulate and change the spec?
This tool is clearly for something related to that (how you call a remote web web service) and clearly people find it, and tools like it valuable. But I don't get it.
This isn't me saying "you kids are dummies for needing this thing" -- I'm asking the opposite: "I don't get it: what important things am I not understanding?"
You can of course provide your own schema. This tool lets you design an API for a web service in a popular schema format called OpenAPI.
In the design view, I suggest having a way to show only part of the OpenAPI YAML spec, beyond code folding, because the full YAML document is a lot to scroll through. A way to jump from the view on the right side to the definition in the YAML spec is also important. I suggest adding triple dots at the end of each to show a menu, with "reveal in spec" or something like that.
This is very polished for an initial release. It's a better intro to OpenAPI for someone who is completely new to it than the SmartBear one. Congrats!
We have a big sidebar update coming up soon, keep an eye on the github issues for more info, and your comments contain some good insights us to think about.
One question - is everything in the original Insomnia in Insomnia Designer too, or are they completely different?
Also, if I use Designer then I prob don't need to use the orgiinal Insomnia, right?