Is Bruno Request-First? When You Need a Design-First Tool

Is Bruno request-first? Yes. Bruno is built for composing, organizing, and sending HTTP requests. You create a collection, add requests, edit .bru files, run calls against an API, and version everything in Git. That workflow is fast, local-first, and useful when you are exploring or testing an API that already exists.

Try Apidog today

But request-first and design-first workflows solve different problems. Request-first asks: how do I call this endpoint? Design-first asks: what should this endpoint be before anyone implements it? If your team is building new APIs, shared internal APIs, or public APIs, that difference matters.

This guide compares Bruno’s request-first model with an OpenAPI-native design-first workflow, then shows when it makes sense to move the API contract to the center of your process.

Request-first vs design-first

Use this as a quick decision table:

Dimension	Request-first, for example Bruno	Design-first, OpenAPI-native
Starting artifact	A request you can send	An API contract, usually an OpenAPI spec
Best for	Exploring and testing existing APIs	Designing new or shared APIs before code
Source of truth	The request collection	The OpenAPI document
Review timing	After endpoints exist	Before server code is written
Design surface	Requests and examples	Visual designer, schema editor, and spec editor
Drift risk	Collections can fall behind the real API	The spec remains the contract to validate against
Git workflow	Strong, via plain-text .bru files	Strong when the OpenAPI spec syncs with Git

Neither approach is wrong. The practical question is whether the API already exists or whether your team is still defining the contract.

How Bruno’s request-first workflow works

Bruno stores API requests as plain-text .bru files in a folder you control. There is no required cloud account, proprietary sync layer, or mandatory hosted workspace. That makes it attractive for developers who want their API client to behave like the rest of their codebase.

This is the core of the Git-native API workflow many teams like: files live in the repo, changes are reviewed in pull requests, and API test updates can move with application code.

Bruno works well when you need to:

• Explore an existing API: point Bruno at a running service, send requests, inspect responses, and iterate quickly.
• Keep API calls local and versioned: store requests beside code and review changes through Git.
• Run everyday API tests: use environment variables, scripts, and assertions for request-level testing.
• Avoid lock-in: keep request definitions in files you own.

A typical request-first workflow looks like this:

1. Start with a running API.
2. Create or import requests.
3. Add environments for local, staging, and production.
4. Send requests and inspect responses.
5. Add scripts and assertions.
6. Commit the request collection to Git.

If your work is mainly consuming, debugging, or verifying APIs that already exist, request-first is often the fastest path. That is also why Bruno compares well against broader platforms in this Bruno alternative breakdown.

Where request-first starts to break down

Request-first becomes harder to scale when the API does not exist yet or when several teams must agree on what it should look like.

1. Requests are examples, not contracts

A request shows one way to call an endpoint. It does not fully define the endpoint contract.

For example, a request can show this payload:

{
  "name": "Ada Lovelace",
  "email": "[e-mail]"
}

But it does not automatically answer contract-level questions like:

• Is email required?
• What format validation applies?
• What happens if name is empty?
• What fields are returned?
• What error schema is used?
• Is this endpoint stable for client teams?

An OpenAPI schema can define those rules explicitly:

components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          minLength: 1
        email:
          type: string
          format: email

That difference matters when the API is still being designed.

2. Collections can drift from the real API

When the request collection is the source of truth, it only reflects what someone has called or tested.

The backend can change by:

• adding a required field
• removing a response property
• tightening validation
• changing an error format
• deprecating a parameter

The request collection may not reveal the drift until a test fails or a client breaks.

A spec-first workflow inverts the dependency:

OpenAPI contract -> implementation -> tests -> docs -> mocks

The contract becomes the reference point, and implementation can be checked against it.

3. Cross-team review is harder before code exists

Reviewing a folder of requests is useful after endpoints exist. It is less effective when you need approval before implementation.

For API design review, teams usually need to inspect:

• resource names
• endpoint paths
• request schemas
• response schemas
• status codes
• error formats
• authentication requirements
• versioning implications

Those are easier to review in a declarative API contract than in a set of example requests.

Bruno is still a good request-first tool. The limitation appears when it is used for a contract-first job.

When design-first is the better workflow

Design-first is most useful when the API is a shared interface, not just a service you are calling after it ships.

Greenfield APIs

When nothing exists yet, start with the OpenAPI spec.

A practical flow:

1. Define paths, methods, schemas, and responses.
2. Review the contract with frontend, backend, product, and QA.
3. Generate mocks or documentation from the spec.
4. Let client teams build against the mock.
5. Implement the backend against the approved contract.
6. Validate implementation and tests against the spec.

This avoids reverse-engineering documentation and mocks from implementation later.

Multi-team internal APIs

If backend and frontend teams are working in parallel, the OpenAPI spec becomes the agreement.

Frontend teams can build against a mock as soon as the contract is approved. Backend teams can implement against the same contract. QA can derive test cases from the expected request and response shapes.

Public APIs

For public APIs, documentation and stability are part of the product.

A maintained OpenAPI contract helps with:

• generated reference documentation
• versioning discipline
• breaking-change review
• SDK generation
• onboarding external developers
• consistent error handling

The rule of thumb: use design-first when people need to agree on the API before code is shipped.

How Apidog supports design-first and spec-first workflows

Apidog is built around a design-first workflow, but it also keeps the OpenAPI-native and Git-friendly properties developers expect.

You can work with the same API project in two ways:

• Visual design mode: define endpoints, request bodies, response schemas, parameters, and reusable components without hand-writing YAML.
• Spec-First Mode: edit the OpenAPI document directly in a code editor, with the spec as the source of truth.

That means different roles can work in the interface that fits them:

Backend engineer -> edits OpenAPI directly
Product engineer -> reviews endpoint structure visually
Frontend engineer -> checks schemas and mocks
QA engineer -> derives test scenarios from the contract

Both views stay connected to the same API contract.

Apidog’s Spec-First Mode also supports two-way Git sync. The OpenAPI spec can live in your repository as a real file, and changes can flow between Git and Apidog. That applies the Git-native workflow Bruno users value to the contract itself, not only to request examples.

You can find the implementation details in the Spec-First Mode documentation.

The result is a workflow that supports both phases:

Design the contract -> review it -> sync with Git -> mock/test/docs -> implement -> verify with requests

For a deeper comparison, see spec-first vs design-first in Apidog.

How to choose the right workflow

Match the tool to the API lifecycle stage.

Use request-first when

• You are consuming an API that already exists.
• You need a lightweight local API client.
• Your main task is sending requests and validating responses.
• You do not need formal API governance.
• A request collection is enough for your team.

Example:

You are integrating with a payment provider.
The API already exists.
You need to test auth, payloads, and responses.
Request-first is a good fit.

Use design-first when

• You are creating a new API.
• Multiple teams depend on the API.
• You need review before implementation.
• You need generated docs, mocks, or SDKs.
• You want the OpenAPI spec to be the source of truth.

Example:

Your backend team is building a user management API.
Frontend needs to start before backend is finished.
QA needs expected schemas and error responses.
Design-first is a better fit.

Use both when

Many teams eventually need both:

1. Design the API contract first.
2. Review and approve the OpenAPI spec.
3. Generate mocks and documentation.
4. Implement the backend.
5. Use request-first testing to verify live endpoints.

Request-first is useful for execution. Design-first is useful for agreement.

Choosing by team maturity

A simple way to decide is to look at your team stage.

• Solo developer or small team consuming APIs
  
  Request-first is usually enough. Bruno’s local-first model keeps the workflow simple.

• Growing team shipping its own APIs
  
  This is the inflection point. Once another team depends on your endpoints, an informal request collection becomes harder to scale. A formal contract starts saving review time and reducing integration bugs.

• Mature organization with public or many internal APIs
  
  Design-first becomes close to required. The OpenAPI spec acts as governance, documentation, onboarding material, and implementation reference.

The practical conclusion: teams often start request-first and grow into design-first as their APIs become contracts other people rely on.

FAQ

Is Bruno request-first or design-first?

Bruno is request-first. Its core model is creating, organizing, and sending HTTP requests stored as plain-text .bru files. That makes it well suited for exploring and testing APIs that already exist.

Can I do design-first work in Bruno?

Not natively in the same way as an OpenAPI-centric design tool. Bruno focuses on requests rather than using an OpenAPI document as the primary source of truth. If you need to define and review an API contract before code, a design-first tool is a better fit.

Do I have to give up Git to use design-first?

No. Git-friendly API work can apply to the OpenAPI spec itself. With Apidog’s Spec-First Mode, the spec can live in your repository and move through pull requests like application code.

What is the main difference between request-first and design-first?

Request-first starts with calls to an API. Design-first starts with the API contract.

In practice:

Request-first: I have an API. Let me call it.
Design-first: I need an API. Let me define the contract first.

Which workflow should I use for a public API?

Use design-first. Public APIs need stable contracts, clear documentation, consistent schemas, and deliberate versioning. An OpenAPI-native workflow gives you a stronger foundation for those requirements.