Forem: Ryan Reynolds

Stop Making Developers Rebuild Your API Collections

Ryan Reynolds — Thu, 20 Nov 2025 17:23:04 +0000

Auto-Generate Bruno Collections From Your OpenAPI Specs

Teams ship OpenAPI specs.
Developers need usable API collections.
Those two things are almost never kept in sync.

Every time a developer starts integrating with your API, they end up:

Importing a Postman file that's already stale
Fixing broken request bodies
Guessing auth flows
Digging through GitHub issues for accurate examples

This is unnecessary friction. And it wastes time at scale.

So I built OpenAPI Catalog, a fully automated pipeline that turns
OpenAPI specs into Bruno collections + clean HTML docs, always
synced to the source of truth.

👉 https://openapicatalog.com/\
👉 Open source repo: https://github.com/rreyn-bruno/openapi-catalog

Why Collections Should Come From the Spec, Not Maintained By Hand

1. Specs are the truth. Collections are the interface.

The spec declares what your API is.
The collection shows developers how to use it.

Today, most companies maintain both manually. That guarantees drift.

When the collection is generated from the spec:

No rot
No missing endpoints
No human error
No out-of-sync environments

This eliminates a huge source of DX pain.

2. Bruno collections are Git-native, local-first, and deterministic

This is the real unlock.

Bruno isn't cloud-locked or bloated. It stores everything in plain
files, diffs cleanly, and works offline. That means an autogenerated
collection becomes a first-class artifact in your repo, just like:

openapi.yaml
SDK code
Migration files
Scripts

You get:

Clear diffs when your API changes
Collections versioned per release tag
CI-driven generation
A reproducible workflow instead of a manual export

This is structurally better than maintaining a Postman export in your
repo.

3. Documentation improves automatically

OpenAPI Catalog generates clean, fast HTML docs for every spec it
processes.

Developers get:

A readable reference
No massive Swagger UI bundles
No Try-It sandbox issues
No need for a separate docs pipeline

Docs and collections now stay perfectly aligned with the spec.

How OpenAPI Catalog Works (Technical Overview)

Discover OpenAPI files across GitHub and other sources
Parse, lint, and validate the spec
Generate a Bruno Collection mirroring the API structure
Produce HTML documentation automatically
Host everything with download links
Rebuild on spec changes from upstream

The system is built to be:

Automated
Deterministic
Scalable
Easy to fork or extend

The entire pipeline is open source:
https://github.com/rreyn-bruno/openapi-catalog

Why API Publishers Should Ship Bruno Collections

Better onboarding

Developers start with working request examples, no editing raw JSON, no fixing broken imports.

Better engineering workflow

API changes become obvious through diffs in both the spec and the
collection.

Better versioning

Collections track release tags, branches, and environments cleanly.

Better ecosystem integration

Bruno collections are portable, local, and friendly to CI systems.

For forward-thinking teams, this becomes part of the release pipeline:

# CI pseudocode
generate-bruno-collection openapi.yaml > collection/
publish collection/ alongside openapi.yaml

Or skip the pipeline entirely and let the catalog do it:

👉 https://openapicatalog.com/

Call for Contributors & API Maintainers

The project is open source and early. Contributions are welcome,
especially around:

New spec sources
Better generators
Improved docs
CI integration examples
API maintainers who want their API indexed

If you maintain an API and want a synced Bruno collection + docs
generated automatically, open an issue or drop your repo.

OpenAPI is the source of truth.
Bruno is the developer interface.
This project connects the two... automatically.

Stop Storing API Collections Outside Git

Ryan Reynolds — Fri, 15 Aug 2025 17:11:52 +0000

Most API clients follow the same tired playbook:

Build a proprietary cloud.
Lock in your formats, workflows, and data.
Charge you extra to secure them.

Meanwhile…

Git has been the foundation of modern software development for over a decade.

It’s where your code, your tests, and your docs already live.

It’s where you’ve invested in security, permissions, audit logs, and backups.

So why are API collections treated like they’re special snowflakes that need their own platform?

Every API collection outside Git means:

2x security models, backup strategies, approvals
No true versioning or history diffs
Fragmented onboarding
A mess

That duplication wastes time, fragments workflows, and increases risk.

The fix is obvious:

Use an API client that allows your collections to be in Git right next to the code they belong to.

No extra layer to manage. No parallel workflows to reconcile.

You get versioning, collaboration, CI/CD, and security for free.

Git-native API clients are inevitable.

💡 Further reading: Why API collections belong in Git

How to Use External Libraries in Bruno Test Scripts

Ryan Reynolds — Tue, 08 Jul 2025 15:05:56 +0000

API Clients are usually powerful… until you try to use the tools you already know — like external libraries (or...cough... Git).

Other platforms require workarounds, sandboxes, and script injections to get basic utilities working. But Bruno takes a different approach.

Bruno runs your test scripts in a real Node.js environment.

That means you can npm install your favorite packages and require() them like you would in any local project.

In this post, we’ll walk through:

💡 Why using external libraries in your test scripts matters
🔍 What Zod is and why it’s useful
🧪 Real-world examples using a pet-themed API and zod
🛠 How to install libraries into your Bruno collection safely

Let’s dive in!

🛑 Heads up: Leveraging external libraries requires using Developer Mode. It's important to be cautious when using this mode as it allows script execution on your machine. Only use Developer Mode when you trust the author of the collection (or if you are the author, of course).

🤔 Why Use External Libraries in API Tests?

Real-world APIs can get complex: nested responses, dynamic data, or custom validations. Instead of writing that logic from scratch, external libraries give you reliable, well-tested tools to:

Format or manipulate data (dayjs)
Validate conditions (joi, zod)
Generate dynamic content (uuid, faker)
Do complex math or logic (mathjs)

In Bruno, you don’t need to hack these in. You just install them.

Bonus: Bruno also includes built-in libraries like chai, axios, ajv, and lodash — no install needed. Learn more in our inbuilt libraries docs.

📚 What Is Zod?

zod is a TypeScript-first schema validation library for JavaScript. It’s lightweight, powerful, and works great for validating API responses in tests.

Here’s what Zod is great at:

Defining strict schemas for expected objects
Parsing and validating incoming data
Throwing clear, readable errors when validation fails

📦 Installing External Libraries in Bruno

To use an external package like zod in your test scripts:

Navigate to your Bruno collection folder:
```
cd path/to/your/bruno-collection
```
Initialize a package.json file:
```
npm init -y
```
Install the external package:
```
npm install zod
```

Bruno will now be able to use the installed package inside your test scripts just like any regular Node.js project.

🐾 Real-World Examples

Let’s walk through two playful but practical examples using Bruno, Zod, and our echo server. You can follow along or grab the collection from GitHub.

📄 Request 1: Validating Response for `Name` and `Type`

{
  "users": [
    { "name": "Bruno", "type": "dog" },
    { "name": "Luna", "type": "cat" },
    { "name": "Ziggy", "type": "bird" }
  ]
}

Test Script:

const { z } = require("zod");
const response = res.getBody();

const UserSchema = z.object({
  name: z.string(),
  type: z.enum(["dog", "cat", "bird"])
});

const Schema = z.object({
  users: z.array(UserSchema)
});

test("Validate response schema structure", () => {
  Schema.parse(response);
});

📄 Request 2: Detailed Pet Validation

{
  "pets": [
    {
      "id": "pet_001",
      "name": "Bruno",
      "age": 4,
      "vaccinated": true,
      "tags": ["friendly", "energetic"]
    },
    {
      "id": "pet_002",
      "name": "Luna",
      "age": 2,
      "vaccinated": false,
      "tags": ["quiet"]
    }
  ]
}

Test Script:

const { z } = require("zod");
const response = res.getBody();

const PetSchema = z.object({
  id: z.string().startsWith("pet_"),
  name: z.string(),
  age: z.number().int().nonnegative(),
  vaccinated: z.boolean(),
  tags: z.array(z.string())
});

const PetsResponseSchema = z.object({
  pets: z.array(PetSchema)
});

test("Valid response structure for pets", () => {
  PetsResponseSchema.parse(response);
});

test("All pets must be vaccinated", () => {
  const unvaccinated = response.pets.filter(pet => !pet.vaccinated);
  if (unvaccinated.length > 0) {
    throw new Error(`Found unvaccinated pets: ${unvaccinated.map(p => p.name).join(", ")}`);
  }
});

✅ Why Bruno’s Approach Wins

Feature	Bruno ✅	Others ❌
Use `require()` like normal Node.js	✅	❌
Install npm packages	✅	❌
Supports any external module (even private)	✅	Limited
Local-first (no cloud storage of secrets/code)	✅	❌

No sandboxes. No evals. No headaches. 🎉

🔗 Try the Demo Yourself

Fetch the full working collection from GitHub or click the button below:

You’ll see the request go out to the echo server, the response come back, and your Zod-powered tests validate the schema.

💬 Final Thoughts

Using external libraries in test scripts shouldn’t be a hassle. Bruno treats your code like actual code — because it is.

We’d love to see what libraries you end up using in Bruno collections. Got something cool to share? Tag us or contribute to docs.usebruno.com.

Happy testing! 🐶

Working with JSON Data in Bruno

Ryan Reynolds — Tue, 08 Jul 2025 11:25:28 +0000

JSON (JavaScript Object Notation) is the go-to format for sending and receiving data in modern web APIs. Its simplicity, readability, and wide support across programming languages make it a favorite among developers. While XML had its moment, JSON has clearly taken the lead, especially in the world of REST APIs.

In this guide, we’ll walk through the basics of JSON architecture and structure, followed by real-world examples of how to access and test JSON properties using Bruno—an open-source, Git-sync'd, API client that puts developers first.

A Quick Primer on JSON

JSON represents data as key-value pairs and supports objects, arrays, strings, numbers, booleans, and null values. Here’s a simple JSON object:

{
  "name": "Bruno",
  "email": "hello@usebruno.com",
  "twitter": "@use_bruno",
  "github": "usebruno"
}

And here's a more complex nested structure:

{
  "items": [
    {
      "orderID": "0000001211",
      "orderInvoiceNo": "1234567",
      "OrderBlocks": [
        {
          "lineNo": 1,
          "productCode": "001"
        },
        {
          "lineNo": 2,
          "productCode": "012"
        }
      ]
    }
  ]
}

Despite its nested nature, the data is easy to work with in Bruno thanks to its built-in JSON viewer, which formats responses cleanly and makes it easy to collapse and expand sections.

Real-World Bruno Test Examples

Want to try this yourself? All examples are available in a public GitHub collection. You can clone it directly, or use the "Fetch in Bruno" button to import them instantly.

✅ Example 1: Validate Key Names and Values

test("OrderBlock has expected lineNo and productCode", () => {
  const jsonData = res.getBody();
  const firstBlock = jsonData?.items?.[0]?.OrderBlocks?.[0];

  expect(firstBlock).to.have.property("lineNo");
  expect(firstBlock).to.have.property("productCode");

  expect(firstBlock.lineNo).to.equal(1);
  expect(firstBlock.productCode).to.equal("001");
});

✅ Example 2: Find a Block by lineNo

test("Find OrderBlock by lineNo", () => {
  const jsonData = res.getBody();
  const blocks = jsonData?.items?.[0]?.OrderBlocks;

  const match = blocks.find(b => b.lineNo === 3);

  expect(match).to.be.an("object");
  expect(match.productCode).to.equal("013");
});

✅ Example 3: Flatten Nested Arrays of lineNo Values

test("Flatten all lineNo arrays", () => {
  const jsonData = res.getBody();
  const blocks = jsonData?.items?.[0]?.OrderBlocks;

  const allLineNos = blocks.flatMap(b => b.lineNo);

  console.log("All lineNos:", allLineNos);
  expect(allLineNos.length).to.be.greaterThan(0);
});

Try It Yourself in Bruno

You can run these tests by cloning the public collection on GitHub. Just click the button below to fetch it directly in Bruno:

Or clone the repo directly: https://github.com/bruno-collections/json-testing-examples

Final Thoughts

JSON is foundational to modern APIs, and Bruno makes working with it simple and elegant. Whether you're debugging a response, writing a test, or building a mock, Bruno helps you focus on what matters — your data.

To learn more, check out the Bruno docs or join the Bruno Discord.