Hacker News new | past | comments | ask | show | jobs | submit login
Show HN: Insomnia Designer – Open-source collaborative editor for API design (insomnia.rest)
317 points by Nijikokun 72 days ago | hide | past | favorite | 83 comments

I love Insomnia and use it almost daily and in the hope the developers/owners are reading here on Hacker News: Please don't make the same mistake as Postman. I used Postman years ago until it shifted from being a simple tool to test and develop REST Apis to something now called "Cloud Collaboration Platform", got way to much bloat and tries to nudge me (or maybe even made it mandatory in the meantime?) into creating a user account etc.

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.

We're extremely aware of what has made Insomnia successful over the last five years and we want to keep applying the same principles going forward. This is a big reason why we're keeping the existing Insomnia application (now named Core) as a separate, standalone app. Simplicity, focus, and usability are key.

Thank you so much for that attitude and I have to add: I'd definetely spend money on a license if there a pro/everyday-user features that make it worth it, while having a free version so that others in the team can still collaborate and use my output/exports. I'd often find it hard to convince teams or new users with which I collaborate to convince to spend money on a tool upfront just so they can collab with me. But if its only additional/pro features, that won't be an issue.

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.

We're tracking that on GitHub. Feel free to follow along or submit additional details :) https://github.com/Kong/insomnia/issues/2082

It sounds like you are the creator/a team member, so I just wanted to give you a data point.

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 currently have a new sync system in beta that works more like Git, making it easier to control what is shared and when. https://support.insomnia.rest/article/67-version-control

Personally I think it's a lost opportunity that you're still not allowing people to save the configuration in the project they're working on.

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.

Can it use an exportable/importable file as source of truth which you can then check into git?

Yes, many teams use the import/export feature to do exactly this.

This is one of the key reasons we didn't build this functionality into Insomnia and instead released a separate application.

Users love our products for their simplicity and the streamlined nature and we fully intend to keep that essence going forward.

Thank you! I understand that from a company valuation/investor perspective it's important to have enterprise features and cloud collaboration / account sign up nonsense. But too many simple tools have gone down that path and ended up becoming bloated and frustrating. Dropbox is a big offender here too IMO.

Thank you. For both the tools you make and this reply explaining your reasoning on this one.

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".

Luckily it is open source https://github.com/Kong/insomnia so if something like that happens, a community KISS fork is possible.

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.

You could try Fiddler; it has a huge feature set along with an old-school UI: https://www.telerik.com/fiddler

While we are giving tips, sometimes all you need is the fetch() api in F12 in your favourite browser. And the good think about using that is you then remember the api better for when you are programming again. I've done this before for simple jobs.

Isn't fiddler intended to be used to capture requests sent from already running apps and not to make standalone requests to APIs? Additionally it is not multi-platform as far as I know, you can only run it on Windows machines.

I've ran it on Linux few years ago. It's a .NET app and it wasn't too hard to make it run with Mono.

I've used Fiddler both for capturing existing requests as well as firing off my own to test an API :) You can create one from scratch or modify one that was previously captured (the latter being really handy for dealing with auth and large payloads).

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.

Lucky for you, I'm a windows 98 kind of guy, i've been thinking about doing a custom theme for a while ;))

I really wish I had the slackmoji of Ballmer pumped right now

I use Postman daily and I have never created an account. I think it only nags you when you start the app for the first time. I just import/export my collections to the git repo of the API I am working at.

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.

I think there are a few plugins that provide that functionality, would love to chat more about the use-case to see what we could do in the future for things like this.

feel free to email - nijiko@konghq.com

I had asked a similar question before, and I think this ^ is exactly why they built Designer and Insomnia Core (the original) as separate products. Freedom of choice ftw!

Can't stress this enough!

As someone who just recently completed a Read API overhaul for NodeBB (https://docs.nodebb.org/api/), the more I read into Swagger/OpenAPI, the more out of my depth I feel.

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.

I think you're being a bit hard on yourself - moving to spec-first is super hard. Erin McKean from Wordnik helped create OpenAPI spec and she talks a lot about how it's a journey to get there.

Don’t worry about it. You have something that works so you are already ahead. Following every trend just drives you crazy.

What I need is a sensible kit of software to let me generate API documentation without the opinions on, "this is actually a web server to be hosted". I just want markdown or HTML outputs without "Try it now!" or other features.

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.

We've been discussing this internally quite a bit and is something we want to provide through our plugin infrastructure which is the ability to choose the type of specification, it's output and preview mechanisms.

This way the workflow can be specialized for your needs.

Have you looked into protobuf? Seems like it should do the trick

This looks like a good product, and I'm happy to hear the "Core" will remain as a dedicated, simple tool.

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)

Wow, big congrats to the folks behind Insomnia. I am amazed at the rate they keep improving it. The tool is ultra polished and the love that goes into it is so clear. If you have not tried it, I recommend it!

I started using this today. It's good so far. I can now stop spinning up swagger editor in a container and work with this. Going to switch over to this fully since I was already using Insomnia.

This is great, but I noticed that the output doesn't fully support OpenAPI 3.0.0, particularly the use of "oneOf" responses. I believe it's because you're calling out to swagger-ui and swagger-ui doesn't support these: https://github.com/swagger-api/swagger-ui/issues/3803

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.

Great point, we started with OpenAPI / Swagger-UI as it's the popular specification but we do want the application to support more specifications and preview / output libraries. We just had to start somewhere.

For people searching for similar tools: I can highly recommend Stoplight Studio. https://stoplight.io/studio/

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

it always outputs broken specs for me

Would love to know more. Can we chat? vincenzo at stoplight dot io

I just asked this on another version of this I saw, but how does this compare to the original Insomnia? Are they two completely different products?

Insomnia is an extremely powerful tool, but most users love it for how simple and easy it is to use. In order to maintain this core tenant, Designer needs to be simple too, which is why we're releasing Insomnia Designer as a separate application, focused entirely on API design.

I want to say that I use Insomnia daily and love it so much more than Postman, thanks for all your work.

I asked the question elsewhere, but this doesn't mean that there's any loss of test functionality in Insomnia Designer compared to the original, right?

Currently, you can do everything you can do in Insomnia Core but it's exposed in a secondary workflow.

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.

It would be great if this supported gRPC. Other than BloomRPC, I'm not aware of any tools like this for protobuf/gRPC APIs.

We've been seeing the popularity of things like grpc and websockets and are currently looking into ways we can support these in the future.

I see that Insomnia Designer supports Graph QL. Are there any templates or tutorials for building something simple using GraphQL?

We have some documentation on GraphQL, would be good to maybe start some tutorials and build guides! Great idea!

+1 for this, maybe the people at Apollo could help?

How do you keep your services Api documentation updated in your organization? Are you generating openapi specs directly from code? Or do you build it with a ui designer tool like this ?

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

Great question.

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.

Thank you for the reply, For node.js, so far I haven't found any good tool to generate openapi specs from code. If by chance you have recommendations I would be happy to know some other complimenting tooling for it

For Ubuntu, both insomnia and insomnia designer point to the same package 'insomnia' on your download page.

Currently working on the builds for linux and windows. Some left over issues from merging repositories. New builds should be up soon!

All that might explain it. Got hit with Smart Screen on Windows and then an error during install that triggered an abort.

The latest build fixes the install issue on windows. It turns out that one of the node modules had a really long path, causing it to exceed the max path length in windows.

Yes - the whole team has been responsive and all over it!

Same issue (Core and Designer instructions are identical) on Ubuntu 19.10 with `sudo snap install insomnia`. About shows "Insomnia REST Client Version 7.1.1"

I found the .deb file on the github releases page at https://github.com/Kong/insomnia/releases

I tried importing a swagger 2.0 json, and I'm not sure it worked right? The debug side works fine, but the designer side just has the json on a single line, and nothing in the left panel.

I assume it's supposed to have something there based on the screenshots where I can manipulate and change the spec?

JSON support is a little bit lacking at the moment, something we plan to address soon. If the JSON isn't private we'd definitely love to take a look, do you mind opening an issue?

Can someone help an old fart here? When I think of "API" I think of, say sections 2 and 3 of the unix man pages. Calling conventions basically. When I write a library I don't need a special tool -- the functions and data structures in my external .h files by definition define the API.

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?"

A web service can provide a schema similar to a header file to define its API but there is no "standard" format for this schema, nor is there a standard location to look for such a thing.

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.


Agree - appreciate the clarity of the answer.

This is nice. I like how there's a switch that flips between design and testing, and how testing has the familiar insomnia view, with environments.

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!

I put in a Feature Request. Since OpenAPI supports file references, and for any API of substance, you'll probably prefer living with the file broken down into logical sections, it's just so much more straightforward to work with. But a lot of libraries and software don't support these references!

Thank you! We hope to continue to make it even better!

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.

I love Insomnia! Also, thank you for making it available on Linux too <3

This is great. I'm a huge fan of Insomnia for testing APIs and I've been looking for a good tool to help with the design aspect.

I used insomnia for a while, it was ok and felt more lightweight than postman. But then after using it for about a month it started crashing for no reason and since then I have tried using it a few more times but it crashes on me Everytime. I even updated to the latest version, did a clean uninstall using iobit and reinstalled but same.

Insomnia is great. Support for Flatpak would be awesome ;-) https://github.com/Kong/insomnia/issues/1812

Insomnia is great. This will be a great addition! However, it annoys me that the image showing the tool is not zoomable or clickable, so you can barely see what it's showing.

That's great feedback. We'll see if we can get that updated.

Love this and especially the Kubernetes features.

One question - is everything in the original Insomnia in Insomnia Designer too, or are they completely different?

Yes, everything in Insomnia (Core) is now part of Insomnia Designer. You will notice the Core interface when switching to "debug" mode for an API spec. This mode provides access to existing Insomnia features to let you manually test and debug your API during the design process.

Is the plan to merge them ever or are they going to stay separate?

Also, if I use Designer then I prob don't need to use the orgiinal Insomnia, right?

Separate! I like to say that designer is more when you're building and creating, and core is when you're trying out other apis or just scratch padding some requests.

Maybe the next step is testing and generating docs, right?

Exactly ;)

Url changed from https://konghq.com/blog/introducing-insomnia-designer-an-ope..., which points to this, which was also the URL in a duplicate thread: https://news.ycombinator.com/item?id=23021368.

I think the URL is different now? The other blog was on Kong's website and was different.

Yes, the submission was originally to Kong and we changed it to what it is now. Does that answer your question or am I missing something?

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact