Forem: Voiden

How to Keep API Docs Consistent with Reusable Blocks

aldin — Thu, 16 Oct 2025 07:59:08 +0000

API docs a mess with endless updates and inconsistent formats? Still copy-pasting headers or error codes across endpoints? Use Voiden's built in reusable blocks feature to write modular components once, import them across the project, save time and avoid the frustration of debugging mismatched specs.

Trying to integrate an API, only to find the docs are a mess. We’ve probably all been there. It doesn't matter if it's a two-month-old startup or an established leader in the space. There's always something (s)lacking.

One endpoint uses id, another user_id, and the error formats change depending on who wrote the page. It’s beyond frustrating, time-wasting, and leads to bugs. There's no single tool that can address and account for all the human-induced issues, but there are areas where we can start. Reusable blocks in Voiden can help solve parts of this issue. They’re simple, help save your time and keep your docs consistent across projects, and work offline in Git.

Why Inconsistent Docs Drive Devs Nuts

There are more than a few reasons why API docs go stale quickly. Yet whatever the reasons may be, the effects are the same. Fru-stra-ti-on. On repeat.

Partially, it has to do with the fact that no one deeply cares about API documentation as long as it works. People just take that it works well for granted. When it causes pain, well, that’s a whole other story.

Devs have been venting about this for years, just check it out on X, Reddit, HN, anywhere really. If you haven’t experienced it first hand (I doubt it), here’s what it usually looks like:

There’s no fun in spending hours doing something that should have taken less than a few minutes. It’s as simple as that.

These mismatches (different field names, outdated endpoints, version-specific gaps, etc.) force devs to debug docs instead of code. Reusable blocks, however, let you write common bits once and reuse them everywhere across the project, cutting out most of the causes for inconsistency in the first place.

Reusable Blocks Remove Duplication and Inconsistencies

Modularity becomes important when there are repetitive components across endpoints, and those are usually headers, query params, response objects, error codes, (environment) variables, etc.

Let’s create small, modular chunks of API documentation in .void files for a dummyjson /posts endpoint. As a starting point, here’s the basic endpoint, with query parameters and documented basics:

Now, if we were to add another GET /objects request, we’d notice some of this stuff is already repeating.

Let’s quickly define BASE_URL within the .env file and set its value to https://dummyjson.com. To use it, just add the variable key in the double curly braces where you’re planning to use it.

Btw, make sure you’re using the correct environment for testing. Check below to see how to select it.

Next, let’s create and import a reusable block named `query.void that holds query parameters.

To create a query parameter table, type /query and hit Enter.

Populate the key-value pairs and add some documentation, if need be.

To reuse it, go to where you need the query params, type @, select Blocks, then pick the query params block, and hit Enter.

If you ever need to edit it, just edit the reusable block, and the changes automatically apply wherever the block is imported.

Oh, and if you need a custom query param for an endpoint, alongside the ones used across the board, just add a new query param table to the endpoint you’re testing. The same goes for headers and other reusable fields.

That’s it. The same approach can be used for other reusable types of API request blocks, saving you tons of time on copy-pasting/typing, but also on applying the changes to these fields in the future and editing once instead of N times (N being the number of endpoints using any given field/object), making your API docs much more consistent.

Let’s Look at the Pros

Reusable blocks are like DRY for API documentation. Write an error format once, use it everywhere. If it changes, update one file, push to Git, and all docs stay consistent. It solves the pain of “reverse engineering JSON responses” by giving devs clear, predictable docs.

Stripe’s docs show how it’s done. Endpoints use the same error and auth formats, no matter the service. You can tell they are at least trying to make it uniform across the platform, if not even reuse certain components to keep things tight.

That is the goal: docs that feel like one voice, not a patchwork of team/mood styles.

Try It Out

Install Voiden: Download the offline app and set up an API repo.

Document your first API endpoint: Start with a single API spec.

Collaborate via Git: Use the in-app terminal to commit your changes, open a PR, and let your team review it using your existing Git tools.

Join our GitHub Discussions to share feedback and shape Voiden's future.

Download Voiden and start building APIs the right way.

API Documentation That Actually Helps Developers: Focus on Their Needs, Not Just the Checklist

aldin — Thu, 02 Oct 2025 08:21:15 +0000

APIs are meant to help solve business challenges, and docs are meant to help solve developers integrate them. This piece shares tips to craft API documentation that helps and supports developers.

Your API could be the best there is, but if the documentation doesn’t help developers, they’ll struggle and, likely, move on. Too often, teams rush documentation to meet deadlines or satisfy product managers, producing a bare-minimum guide that confuses users. Even when the intention is to write it properly, internal biases and assumptions kick in.

Great documentation, on the other hand, puts users first. It’s designed around how users think, work, and solve problems. By understanding your userbase and looking your API through their eyes, you can create a guide that makes integration easy, boosts adoption, and cuts down on support questions saving everyone involved time and money.

This article shares tips to craft API documentation that supports developers, focuses on their common tasks and workflows, and not on whatever the internal priorities may be.

Know Your Developers and Write for Them

Great API documentation starts with knowing who’s using it. Developers have different needs: frontend folks might need examples for building user interfaces, backend engineers want detailed data structures, and QA teams care primarily about error handling.

Spend time understanding what your developers need. Are they building mobile apps? Automating workflows? Testing integrations? Talk to developers, run surveys, and review support tickets. Their insights shape every word you write, even the format. Keep terminology and formatting consistent, like using the same style for endpoint descriptions, so developers can navigate without effort. And just avoid jargon.

Don’t just write to satisfy a deadline or a PM’s checklist. Instead, make your opening section answer, “Why should developers care?” Show how your API solves their specific problems, whether it’s streamlining payments or fetching data faster. A simple and to-the-point overview grabs their attention and sets the tone.

To make documentation truly useful, avoid standalone developer portals or hidden tabs that feel detached from coding. Rather, integrate API docs into developer workflows. Store them in a Git-based setup, alongside the codebase, so devs (yes, the users) can access and tailor docs locally for their needs in the same workflow they use for development. This lets them add examples of their own, track versions, spot outdated endpoint details, and keep docs in sync with their code changes.

Let developers contribute to the docs to reflect their real-world use. This makes documentation a living resource, driven by how developers actually use the API, not just internal assumptions. By enabling easy updates and (local or actual) contributions, you give developers control, keeping docs accurate and relevant for their needs.

By putting users’ needs first, you create documentation that feels like a trusted guide, not a mandatory deliverable that might likely already be outdated on day 2.

Build a Structure Around How Developers Work

Your documentation should match how developers approach your API, guiding them from their first glance to full integration.

Start with a quickstart guide that gets them making a call in 3 minutes or less. Cover basics like getting an API key and sending a simple request, so even beginners can jump in. For the main reference, detail each endpoint with its method, path, purpose, parameters, types, limits, responses, and error codes.

This gives developers a clear map, but it’s not enough to just list facts.

Think about their workflow: what tasks do they tackle first? What problems do they need to solve?

Show the API in Action with Practical Examples

Developers need to see your API solving their challenges. Create guides for tasks they do often, like paginating user lists, building a checkout flow, or integrating with a CRM - whichever it is.

An error-handling section with common issues and fixes, like correcting a 401 error by checking the API key, helps them troubleshoot independently.

Provide example apps/demos in public repositories. These ready-to-run apps, needing only a key swap, show real uses, like fetching user profiles or automating notifications. They let developers test-drive your API in a practical context, making adoption easier. By focusing on tasks developers care about, your documentation becomes a tool that brings the API to life.

Write clearly, using short paragraphs and consistent formatting, and choose language that works for global audiences, keeping translation in mind.

By making documentation easy to read, you help developers focus on building, not deciphering.

Here are a couple of pieces of advice when it comes to treating API docs:

Make API docs a core part of your APIs and revisit them regularly to keep the docs useful.
Use versioning, as with your APIs, to support users on older versions while adding and documenting new features.
Check content after API updates to keep it accurate and remove outdated details.
Assign someone on your team to oversee documentation, ensuring it stays clear and consistent, even if it’s not their only job.
Make documentation part of a broader API governance plan, where team-wide standards keep everything aligned.

Wrap-Up: Documentation That Works for Developers

Great API documentation isn’t about meeting requirements or impressing managers. By understanding developer needs, focusing on their tasks and workflows, and listening to their feedback, organizations create guides that make their APIs easy to use and adopt.

In order to get there, use clear language, practical examples, and a structure that matches how developers work. As you write or update your documentation, keep developers’ needs at the heart of every choice, ensuring your API becomes their go-to solution.

Streamline API Testing with Reusable Building Blocks

aldin — Wed, 17 Sep 2025 12:59:57 +0000

Create reusable API request blocks in Voiden to eliminate repetition, streamline testing, and run locally for instant feedback.

Repetition, a time-churning enemy of developers. Remember the time when copy-pasting code was a universal problem in software engineering? Then abstractions came and solved it (functions, libraries, frameworks, etc).

API tooling, however, still grapples with a similar problem: redefining the same authentication tokens, headers, or parameters for every endpoint test. This manual repetition wastes time and invites errors. Copying and pasting all across the collections is somehow considered a way to get things done faster?! Tabs keep the truth across the tools, along with half a dozen other tooling “necessary” to wrap it all up.

Well, Voiden has now removed the duplication from API tooling, applying the DRY (Don’t Repeat Yourself) principle, streamlining workflows, and giving developers control over their API testing process.

From Code to APIs: The Repetition Problem

In the (relatively) early days of software engineering, developers routinely copied and pasted code for common tasks like string manipulation, file handling, sorting algorithms - you name it. A single change that introduces a change in logic meant updating every instance manually. A paradigm change helped build reusable structures, sharing them across the project (or across different projects, even).

In today’s API tooling, testing an API means creating collections where each request often requires redefining the same authentication tokens, headers, or query parameters.

Need to test 50 endpoints?

You’re either manually setting up OAuth2 tokens or rate-limit headers for each one, or copying and pasting across requests. Collections and environments do help, but they still require manual duplication across workspaces or teams.

Voiden.md solves this by bringing software engineering’s modular philosophy to API testing. Its reusable API blocks let you define common elements such as headers, query parameters, etc., and reuse them across your projects, just like you would do in the codebase. Voiden centralizes your workflow in a single, offline, Git-tracked workspace, giving you control and eliminating the repetitive chaos.

How Voiden’s Reusable Blocks Work

Voiden lets you define common repetitive API elements, like authentication tokens or query parameters, in its .void files, and you can import these blocks into other .void files. These files are simple Markdown files, simplifying documentation of the APIs, just adjusted for Voiden execution.

This approach eliminates the repetitive setup needed (at the moment of writing this blog post) in every alternative API tool out there.

Let’s say you’re testing the DummyJSON API’s endpoints (e.g., a https://dummyjson.com/docs/posts ), which enables filtering results by using query parameters.

Here’s how to create a reusable block in Voiden:

Hit the Ctrl/Cmd+Enter to create a new project file
1. You can name it query.void and save it with Ctrl/Cmd + S
Add a markdown title to describe the file
1. Type ## for H2 styling and add Reusable Query Params Block, for example
Type /query and hit Enter
1. That will create an HTTP query params key-value table
2. Now populate the table with limit and skip fields along with their values
Optionally, document the fields from the query params table

You should see something like this:

Now you’re ready to use this without having to type it all over again across the project by simply importing it.

Let’s say we already created a flow for triggering the /posts endpoint, but we want to add the query parameters on top of it. (If not, you can learn here how to do that)

You should already see something like this:

To import query params block type @, select Blocks, select the name of the block file (in this case, query.void), and finally select the block you want to import from that file. In this case, the query-table.

That’s it. You can repeat the same for any endpoint that uses these query params without having to define them ever again. Just import and run. No more redundancy.

Getting Started

Want to test and document APIs without the repetition mess?

Download the offline app from voiden.md and set up an API repo.
Create a couple of .void files, one per endpoint you’re testing.
- Alternatively, import your existing Postman collection.
Detect the bits that can be reused, and extract them by following the steps provided above.
Execute endpoints in Voiden and validate responses.

Sounds like a good step towards simplifying API tooling workflows? Join our GitHub Discussions to share feedback and shape Voiden.

Why API tooling needs a reset (and what we're doing about it)

aldin — Wed, 03 Sep 2025 07:40:30 +0000

Building and testing APIs feels all over the place nowadays. It's a pain, it wastes time, causes errors, and frustrates everyone involved. This post dives into why API tooling is such a headache, why the industry keeps making it worse, and how Voiden makes life easier for developers.

What’s Going Wrong

Well, a lot of things, really.

Let’s talk real-life examples: A retail app team was rushing to launch a new feature for real-time order tracking. The backend team updated the API specs in one tool, but the frontend team was working off outdated docs stored in another platform. The frontend built the UI expecting a different response format, say, a nested JSON object, but the backend team switched to a flat structure. When they integrated, the order tracking broke, showing wrong delivery statuses to customers. Integration testing caught it, but not before the team lost hours debugging, with frontend and backend pointing fingers over whose spec was right.

This isn’t a one-off. When teams rely on 5-6 apps for designing, testing, and documenting APIs, workflows get clunky and confusing. Specs, tests, and docs live in separate places, so they fall out of sync, leading to outdated info and integration failures. Frontend developers build to a spec that’s no longer valid, backend developers push updates that don’t make it to the docs, and QA teams are left guessing what’s supposed to work. On top of that, online platforms charge per-user fees, track your data, and force you into their cloud-based setups, leaving you stuck with their bugs and downtime.

This mess slows down entire projects. Teams miss deadlines, clients lose trust, and developers burn out from endless context-switching between tools. Or at the very least, you’ve got plenty of frustrated developers. Imagine spending half your day flipping between apps, double-checking specs, or arguing over which version of the docs is current. It’s death by a thousand cuts for developers, tech leads, QAs, and DevOps trying to ship reliable software.

Why is it happening? Tooling companies aren’t building for developers. They’re building for their own bottom line. They churn out platforms with shiny features like AI dashboards or enterprise integrations, chasing subscriptions instead of solving real problems. That results in platforms that lock teams in, collect data, and add complexity.

If we want API development to be less of a headache, we need tools that actually understand how developers work, tools that keep teams aligned, cut the noise, and let code do the talking.

What are we doing about it?

You can read the story behind the frustration that resulted in Voiden being built. The idea was straightforward: stop forcing developers to adapt to tools and start building a tool that adapts to developers, a single tool for the API workflow.

Voiden, while still early-stage, is free, VC-independent, lightweight, and offline. You don’t need an account, and no data gets sent to a cloud server. An in-app terminal is there, and a fully markdown-based editor for you to document everything about your APIs.

Something that isn’t available in alternative tools is the DRY principle. In Voiden, you can define elements you want to reuse across APIs and simply import them where you need them. For example, headers, query parameters, or anything else that makes sense to be reused. Just define, import, and save hours on not repeating yourself.

When you’re happy with the state of the API, use Git commands in the terminal to version it or collaborate with teammates. None of that pay-per-seat nonsense.

How Voiden Works: Simpler, Code-Based, Team-Friendly

Voiden takes the mess out of API development by letting you design, test, and document APIs in one place, right next to your codebase. It’s built for developers who live in editors and Git repos, ensuring frontend, backend, QA, and DevOps all work from the same source of truth.

What API workflows should look like:

Code-like workflow: Write APIs in .void Markdown files, stored in your Git repo alongside your code, so specs, tests, and docs are always in sync.

No tool-hopping: Create specs, run tests, and generate docs without leaving your editor, keeping frontend and backend teams aligned.

DRY by design: Define reusable elements like headers or error codes once, then import them across APIs to save time and avoid mistakes.

Extensible: Install (or build yourself) plugins for any additional features you may need.

Offline and free: No cloud subscriptions, no data tracking, just your machine and your code.

Here’s an example of how API workflows look like in Voiden.

You can define common headers or query params once, and import them across the project to avoid repetition. Docs are built within the same file, so everyone’s working off the same info. Push it to your Git repo using the in-app terminal, and it’s ready for your CI/CD pipeline. No extra apps, no outdated docs, no frontend-backend arguments.

Why this matters?

The API tooling world is a mess because it’s built to serve vendors, not developers. Companies keep pushing platforms that trap teams in pricey subscriptions, snoop on your data, and force you to juggle multiple apps just to keep specs aligned.

The fallout? All over the place. It’s a cycle of frustration that slows down projects and burns everyone out.

By keeping specs, tests, and docs together in a simple, code-based workflow, Voiden cuts the noise and lets teams focus on what they do best: writing code and shipping features.

Next step? Take five minutes to try Voiden with one API. You’ll get to feel firsthand how it keeps your APIs aligned and cuts through the noise of traditional tooling. Download here and rethink how APIs should be built.

How to test and document an API without ever leaving the editor

aldin — Tue, 26 Aug 2025 06:50:36 +0000

Tabbing between browser pages, Postman, and doc platforms for API testing and documentation creates stale docs and kills productivity. Voiden's markdown-style files let you spec, test, and document APIs offline in one place, using a Git-based workflow you already know, without ever having to leave the editor.

The Problem: Tool-Switching Wrecks API Workflows

Managing APIs across multiple tools is a productivity killer. You’re stuck juggling Postman (or any of its lookalike clones) for tests, a browser for endpoint checks, and a platform like Confluence or Notion for docs. The result? A fragmented, frustrating workflow:

Here’s a scenario: Mid-sprint, you’re debugging an API. Postman shows a 200, but the docs aren’t really up to date; they list an old endpoint version. You go to the codebase, find a new response schema, and now that everything is sorted out, the Postman cloud hangs, forcing you to re-run tests. Time wasted chasing inconsistencies and retyping docs. Mouse clicking, tabbing, jumping between tools, and figuring out why things aren’t the same across the board - all checked. A remotely optimal dev experience, nowhere to be found.

This fragmented approach doesn’t just waste time. It introduces errors as well.

Disconnected tools mean manual updates, leading to outdated documentation that confuses teams and stakeholders. Postman’s cloud-based collections, for instance, live outside your codebase, forcing you to export and sync manually, which disrupts your workflow. Tools used for general documentation usually lack the native integration with your repo needed for seamless API development. The constant context-switching between tools slows down collaboration and makes it harder (impossible, really) to maintain a single source of truth for your APIs.

Voiden’s Approach: Markdown-Powered API Workflow

Voiden eliminates these pain points by allowing you to define, test, and document APIs in Markdown-style .void files, all in its offline editor. Specs live in your repo, versioned with Git, with live API responses for docs that stay accurate. No tool-switching or cloud syncs. Teams using Voiden report are halving their API documentation time, keeping specs in sync with code which saves even more time in the future.

.void files are designed to be lightweight and intuitive, combining API specifications, tests, and documentation in a single, human-readable format. Using Markdown’s simplicity, you can define endpoints, write test cases, and embed live response data directly in the editor.

For example, a .void file might include a POST request definition, a test to validate the response status, and inline documentation, imported headers for element reusability and following the DRY principle, all sitting together. Because these files are stored in your filebase, they are Git-friendly, every change is easily versioned, trackable, and reviewable through pull requests, just like your code. This approach ensures your API specs and docs are always in sync with your codebase, reducing errors and eliminating the need for external platforms. Plus, Voiden’s offline-first design means you can work anywhere, even without an internet connection (well, for docs and localhost testing), with no safety issues, or an account.

Here’s an example of Voiden usage:

Getting Started

Want to test and document APIs without the tool-switching grind?

Start with Voiden:

Download the offline app from voiden.md and set up an API repo.
Create your .void file.
Run tests in Voiden’s editor, validate responses, and add docs with live results.
Document one API endpoint and commit it to Git for a PR review.

To make the transition even smoother, Voiden supports importing existing Postman collections with a single click, converting them into .void files that integrate seamlessly into your repo. This eliminates the hassle of rewriting specs from scratch. Read more about migrating your Postman collections here. Join our GitHub Discussions to share feedback and shape Voiden.

Keep API Work Local: Why Offline-First Beats Cloud-Based Tools?

aldin — Fri, 08 Aug 2025 16:44:17 +0000

Cloud-based API tools like Postman can expose your data, and leave you stuck when servers fail or docs lag. Offline-first API workflows offer better security, efficiency, and developer control.

The Trouble with Cloud-Based API Tools

You’re in the middle of debugging an API, and your cloud-based tool (say, Postman) freezes because the servers are down. Or the API docs you’re relying on are outdated, sending you on a wild goose chase. Are these just glitches, or are they symptoms of a workflow that’s too dependent on the cloud even if it doesn’t belong to it?

Where it falls apart:

Data risks: Storing API specs and keys on third-party servers invites trouble. Not once have people pointed to breaches or outages where cloud tools left sensitive data vulnerable.
Tied to the internet: No connection, no work. Even on localhost?! Coding at a remote site or during a server outage? You’re out of luck.
Fragmented flow: Switching between the editor, a testing app, and a docs platform breaks the rhythm and risks stale specs. And what’s with all the tabs and mouse commands.
Vendor lock: Proprietary formats and per-seat fees ties teams to a tool’s ecosystem, limiting options and budget.

Real scenario: You’re racing to meet a deadline, but the cloud-hosted API docs don’t match the live endpoint. You lose an hour (that’s me being an optimist) verifying changes, momentum gone.

Offline-First: The only logical API workflow

Offline-first API workflows put you in control. Using local files you define, test, and document APIs right in your editor, synced with Git. It’s a setup that fits how developers actually work. You know, type, hotkey, enter, tab (not that tab), terminal… the usual dev flow.

Why it’s better:

Secure by nature: Keep your API specs and credentials local, away from third-party servers that could be breached.
Work anywhere: Test and document APIs offline or on localhost. No Wi-Fi? Unless it’s a prod thing and you need THAT environment specifically, you keep going.
Stay focused: Write specs, run tests, and create docs in one place - your editor. No more app-hopping.
Dev-first: Version control tracks changes, simplifies collaboration, and lets you roll back without a fuss. Hotkeys and reusable components keep it DRY, like your code.
No hidden costs: Your offline app and Git are free, scaling with your team without extra fees.

Example: Imagine an executable markdown file (say, an example.void in your Voiden project). It defines your endpoint, explains whatever you need it to, lets you select the localhost environment, and you run an API test. It’s all on your machine, is not hosted, works with no internet, introduces 0 additional safety issues, and you can still version control it and collaborate with the team via Git. Try doing that when Postman’s servers are napping.

Hint:

Why We Had to Rethink API Work

This whole mess with cloud-based API tools shows we’ve been too quick to trade control for shiny dashboards (and some data gathering, per-seat fees, lock in, oh my…). But do developers really need another subscription or clunky UI, or an API tool that feels like an extension of their code. Offline-first workflows are a wake-up call: your API work can be as lean and flexible as your development process.

This isn’t about swearing off the cloud. You’ll still hit live endpoints for real requests. It’s rather about keeping the core of your API work (specs, tests, docs) secure, local, and under your control.

Where to Go from Here

The shift to offline-first isn’t just about dodging cloud pitfalls. The shift to offline is about building a workflow that mirrors how you work as a developer. Imagine API specs that live alongside your code, evolving with every commit, always in sync. Picture a process where your docs aren’t a separate chore but a natural output of your work, as easy as writing a README. The offline-first approach turns API development into something that feels like coding: deliberate, iterative, and yours.

Voiden is on that path. You can help shape it by joining its GitHub Discussions.

Rethinking DevTools: Escaping the Cloud and SaaS Trap

aldin — Wed, 06 Aug 2025 06:09:44 +0000

If not for a gazillion other reasons, a recent outage from Postman should remind us again why proper design decisions matter in devtools.

API workflows shouldn’t live in the cloud.
A LOT of devtools shouldn’t live in the cloud.
Some tools can’t work without it, all good.
But a whole lot of them are there just because of some poor design choices.

Yet…
No cloud? No outage.
No cloud? No sync issues.
No cloud? No data security gaps.
So why keep forcing it where it doesn’t belong?

And it’s not even just the cloud. Cloud is awesome for some stuff.
SaaS-like designs are dragging devtools into the same trap.

As a matter of fact, devtools in general shouldn’t feel like SaaS platforms. Unless we’re going through app usage dashboards - tabs, and mouse actions are not built for devs.

Devtools should prioritize developer control, not just pay-per-seat subscriptions.

Goodbye Postman collections, hello Markdown specs

aldin — Tue, 22 Jul 2025 04:26:22 +0000

TL;DR

Postman’s collections are bloated, paywalled, and siloed from your codebase. Voiden is an offline, lightweight Postman alternative. It uses Markdown-style files to enable you to spec, test, and document your APIs in a single place, leveraging a code-like workflow that you already know and understand.

The Problem: Postman Collections Create Friction

Postman's collection-based approach using JSON or YAML files, cloud dashboards, and a complex UI promises seamless API workflows, but it often slows developers down with unnecessary hurdles:

Paywall barriers: The free plan caps you at 25 collection runs, 3 collaborators, and one private API. Need more? Pay $14–$49 per user per month. Scaling the team is a budget burden.
Siloed specs: Collections live in Postman’s cloud, detached from your repo. Syncing them to Git requires manual exports, breaking your workflow’s rhythm.
Cluttered and rigid: The UI buries simple tasks in menus, and collections don’t support reusable components. Docs are separate, leaving you without a single source of truth.

Think of this scenario: You’re debugging an API mid-sprint, but Postman’s free tier stops you at 25 runs. Your teammate’s changes are stuck in the cloud, and syncing them to your repo means tedious copy-pasting. And needing an internet connection to test the localhost endpoint… that’s a bottleneck, not a workflow.

Aspect	Postman	Voiden
Monetization	Free tier + paid plans ($14–$49/user/month).	Free. Plugins can be monetized, but none are mandatory.
Free plan limitations	25 collection runs, 3 collaborators, 1 private API, unlimited public APIs.	None. Unlimited use.
How API calls are made	Through a proxy server.	From your computer.
Where does it work	Online, logged in.	Local desktop application. No login. No account.
Collaboration	Cloud pay-per-seat paywall.	Git.
Strengths	Widely adopted. Mature. Feature-rich.	Lightweight. Offline. Reusable building blocks. Specs in Markdown-based repos. Feels like coding.
Weaknesses	Paywalled features. Cloud-dependent. Siloed specs. Complex UI. No reusability.	Early-stage. Small community. Fewer features shipped.

Postman’s enterprise focus and heavy UI frustrate indie hackers and small teams. Voiden’s markdown-based, Git-native workspace keeps APIs simple, code-adjacent, and free of SaaS constraints.

Workflow: How do I switch from Postman to Voiden?

Voiden lets you trade Postman’s collections for markdown-style .void files in your repo, using a workflow that feels like coding. Here’s how to make the switch:

Step 1: Import a Postman Collection

Export your Postman collection and add it to a Voiden project.

Step 2: Generate Voiden files

In the top right corner of the imported Postman collection, there should be a Generate Voiden files button. Click it.

The result is a newly generated Directory holding all of the collection’s API specs.

Note that I also created a .env file, which holds a token needed for running this endpoint successfully.

Step 3: Edit, Test, Document, and Commit

Now you can edit generated .void files, adding docs, tests, changing the payload, etc.

Hit the Ctrl/Cmd + Enter to run it.

The right-hand side opens a panel with response (and request) details.

When happy with the state of the API, head over to the in-app terminal, commit the changes, and collaborate as developers do. Via Git.

That’s it.
This approach skips Postman’s cloud dependency and UI clutter, keeping your APIs in your repo, where they belong.

Why This Wins

Voiden’s markdown-based workflow fixes Postman’s pain points for those among you who value code over dashboards:

No paywalls: Free, no limits, no per-user fees. Postman’s $14–$49/month plans are a burden.
Fast migration: One click converts Postman collections to .void files, no hassle.
Code-like simplicity: Markdown is clean, reusable, and editor-friendly. Git tracks every change, unlike Postman’s siloed setup.
Offline control: Specs stay in your repo, not a random cloud. And you can work anywhere, with no sync issues.
Postman’s costs and complexity slow you down. Voiden’s lean, Git-integrated approach keeps you moving.

Getting Started

Ready to drop Postman? Try Voiden:

Install Voiden: Download the offline app from voiden.md and set up an API repo.
Migrate your first Postman collection: Start with a single API spec.
Collaborate via Git: Commit your spec, open a PR, and let your team review it using your existing Git tools.

Join our GitHub Discussions to share feedback and shape Voiden's future. Download Voiden and start building APIs the right way.

Why does Voiden not have "Teams"?

aldin — Wed, 02 Jul 2025 11:24:30 +0000

Instead of building roles, we built around Git - your team structure and collaboration is already there.

Voiden, a free, offline API workspace, says no to SaaS "Teams" features because they're bloated, expensive, and break developer workflows. Git is the real collaboration engine. It's free, familiar, and tied to your codebase.

The Problem: SaaS "Teams" Features == Overhead and Lock-In

Devtools in general, but also API tools, still push "Teams" features as the answer to collaboration. Shared workspaces, real-time edits, cloud-synced dashboards… Sounds great, right? Wrong.

For devs, SaaS solutions around devtools create more problems than they solve.

Per-seat greed: Adding a teammate means another license fee. Scaling from five to fifty devs? Your budget's toast, and managing access becomes a part-time job.
Codebase silos: These tools trap your API specs in their cloud platforms, disconnected from your repo. Syncing them feels like duct-taping mismatched systems.
Version chaos: "Real-time" collaboration invites chaos. Multiple devs editing a spec can cause overwrites or conflicts, with no clear version history to fall back on.

Not convinced? Well, picture this:
For the sake of example, let's imagine that there is an API platform named SaaSman.
Your team's rushing to update an API spec before a sprint deadline, and SaaSman locks out a dev due to a forgotten license tier, and another's changes get lost in a sync error. Hours vanish on fixing permissions and recovering work. That's not collaboration. That's a nightmare. SaaSman's greed could have just cost you a release.

Voiden's Approach: Git as the Collaboration Backbone

Instead of mimicking SaaS tooling, Voiden leans on Git for collaboration.

Why introduce charts nobody asked for, to account for a feature nobody needs, when Git, your trusted and battle-tested tooling, is fully able to handle collaboration without the overhead?

SaaS features add overhead. Git cuts through it.

Here's why:

Free and scalable: Git is free and scales without restriction. "Add" teammates without worrying about license fees or access tiers.
Repo-integrated: API specs live as .void Markdown files in your repo, versioned alongside your code. No external platforms or manual syncs required.
Traceable changes: Git's commits and PRs log every edit to your API specs, preventing overwrites.

You already collaborate on your codebase with the help of some version control systems. Voiden extends that workflow to APIs, letting you define, review, and merge specs using the same tools.

Workflow: Collaborative APIs with Git

Voiden's choice to skip teams and go for the simple solution is neither ideological nor philosophical. It's just practical.

By building on Git, collaboration on APIs becomes a natural extension of your existing workflow, giving you full control over it.

Here's how it works:

Step 1: Define APIs in Markdown

Create API specs in .void Markdown files, stored in your repo (e.g., apis/users/spec.void). These files are lightweight, human-readable, and Git-friendly.

Step 2: Collaborate via Git PRs

Commit your .void files and open a pull request. Teammates review changes using GitHub, GitLab, or Bitbucket, just like they review code. No proprietary "Teams" interface. Just familiar PR comments and diffs tracking every change.

Step 3: Merge and Publish

Once approved, merge the PR to update the API spec. Git's history ensures every change is traceable, and the spec stays in sync with your codebase. Deploy without SaaS sync errors in sight.

This workflow skips the chaos of tools like SaaSman, where "Teams" features force you into their ecosystem. Git keeps it simple, free, and developer-first.

Why This Wins?

The Git approach isn't a workaround. It's a better way (arguably THE BEST way) to collaborate on all things dev, APIs included.

What sets it apart:

Zero cost: Git scales to any team size, free of charge. No budget fights, no license tiers, no per-seat charges, just code-like collaboration.
Offline and secure: Keep sensitive API specs in your repo, not a third-party cloud. Work anywhere, anytime, without sync dependencies.
Code-synced precision: Git's versioning ties your API specs to your codebase, with every change tracked and reversible.
No learning curve: Use Git, Markdown, (in-app) system terminal, and skills you already have. No learning curve for yet another SaaS dashboard.

SaaS tools like SaaSman lock you into their world. There are paywalls, silos, and sync errors included. Voiden frees you to spec, test, and document APIs in the same way you deal with your codebase, with Git as the backbone.

Getting Started

Ready to ditch SaaS "Teams" chaos? Here's how to start with Voiden:

Install Voiden: Download the offline app from voiden.md and set up an API repo.
Create your first .void file: Start with a single API spec.
Collaborate via Git: Commit your spec, open a PR, and let your team review it using your existing Git tools.

Join our GitHub Discussions to share feedback and shape Voiden's future.
Download Voiden and start building APIs the right way.

Why API design is a mess, and how could a git-native tool help?

aldin — Tue, 20 May 2025 12:59:30 +0000

In my dev years and throughout my devrel career, I’ve spent A LOT of time wrangling APIs and devtools (together and separately).

API governance is a pain, been for a while.
Cloud-sync which you don't feel comfortable with, scattered or non-existent docs, rewriting the same stuff all over again, and don’t even get me started on the tools that feel like a full-on enterprise bloat.

Been there, cursed that, got frustrated - a LOT.

The API workflow mess

Well, just recently I got affiliated with Voiden.md. Given this recent affiliation, I’ve been digging into API tools again. You know, checking what works, what is painful, etc. And I want your take as well.

API specs and docs are critical for public-facing microservices, and some internal ones may need them even more. They’re a mess to manage. Currently, we have sources of truth scattered everywhere, specs drifting from code, docs living in another tool, you have some dashboards that nobody checks, and overall, governance is pure chaos.

Most tools don’t help:

Cloud sync feels like a data leak waiting to happen.
Bloated UIs waste time when you just need a quick endpoint test.
Specs and docs in separate places kill your flow.
And wth is real-time collaboration? Make. Your. Own. Branch.

Naturally, I checked out the landscape to see what's what.
Here’s what I found, in short, straight from using them.

API tools: what works, what doesn’t

Postman

Good: Enterprise-ready and collaborative, CI/CD integration, flows, lots of everything you may eventually need.

Bad: UI feels cluttered for small projects, free tier caps at 25 collection runs, cloud sync is not for privacy nerds. One change starts a chain reaction.

Best for: Big teams with end-to-end API needs, and stable APIs that don’t change.

Insomnia

Good: OpenAPI focus, cloud or local sync, solid for structured designs.

Bad: No built-in docs, limited reusability, limited extensibility, that cloud-sync thingy all over again.

Best for: Teams all-in on OpenAPI.

Hoppscotch

Good: Fast, free, browser-only testing with unlimited workspaces.

Bad: No Git, no reusable components, no docs, too basic for complex APIs.

Best for: Frontend devs doing quick in-browser checks.

Apidog

Good: Cheaper than Postman, cloud collab, mock servers.

Bad: Free tier limitations. Cloud-only unless you pay for on-prem.

Best for: Enterprise on a budget.

Bruno

Good: Open-source, offline, git-sync, tests for DevOps pipelines.

Bad: No docs, free-tier testing limited.

Best for: Git-loving OSS fans.

Yaak

Good: Open-source, offline, git-sync, dynamic requests for flexible setups.

Bad: No docs, experimental plugins.

Best for: OSS fans, distributed system builders.

Hurl:

Good: CLI testing for minimal setups, great for scripts.

Bad: Only for running APIs, not designing. No UI, no extensibility.

Best for: CLI purists.

Voiden (my thing)

Good: Git-native, offline, markdown for specs/docs/tests. It imports Postman and enables reusable blocks and plugins.

Bad: Early days, small community, features still in development.

Best for: Devs who treat APIs like code, and hate cloud sync.

Why Voiden makes sense

Voiden is built like software.
Specs are markdown, versioned in Git, and offline-first.
Specs and docs kept together, blocks reusable across the project.
In-app terminal with git gives you branches, diffs, and governance without real-time sync clutter.

Need nothing but a simple GET API call?

Here is what the simplest of calls would look like:

How to reproduce it:

Hit Cmd+N (Mac) or Ctrl+N (Win/Linux) to create a new file.
Type /endpoint to create a new (GET by default) request block.
Type or paste the URL you want to trigger a GET request to.
Hit Cmd+Enter (Mac) or Ctrl+Enter (Win/Linux) to run it.

And now you check the response.

You need something more complex than that?

No problem.

Hit Cmd+N (Mac) or Ctrl+N (Win/Linux) to create a new file.
Type /endpoint to create a new (GET by default) request block.
Replace GET with POST.
Type or paste the URL you want to trigger a request to.
Type /headers to add a API Headers block.
Populate the key-value pairs of the headers block.
Type /json to add a API Body block.
Populate the JSON block with the request body object.
Hit Cmd+Enter (Mac) or Ctrl+Enter (Win/Linux) to run it.

You can run requests with a keystroke and see responses instantly in the panel. Document your endpoints naturally using plain Markdown: descriptions, examples, even error cases. No switching tabs, no sync delays, just specs that live where they should: with your code.

Your API pain points

We’ve all got scars: specs out of sync, cloud sync crashing, tools promising the world and delivering bugs. I’ve raged at Postman’s UI lag. What’s your deal? How do you keep API specs and docs in check? Specifically:

How do you sync specs with code or microservices?
What hacks fix governance or reusability?
How do you handle specs and docs being split?

Hit the comments with your pain points, workflows, or tools I missed. I may be with Voiden, but I’m here to learn what devs like you need. Let’s sort this API mess out, once and for all.