Bruno é Request-First? Quando Usar Ferramenta Design-First

Bruno é request-first: você cria uma coleção, adiciona requisições HTTP, salva tudo em arquivos .bru, executa chamadas e versiona no Git. Esse fluxo é rápido e eficiente quando a API já existe. Mas, quando a equipe precisa definir uma API antes da implementação, a pergunta muda de “como eu chamo este endpoint?” para “qual deve ser o contrato deste endpoint?”.

Experimente o Apidog hoje

Request-first vs design-first: escolha pelo ponto de partida

As duas abordagens resolvem problemas diferentes. Use esta comparação como guia prático:

Dimensão	Request-first, como Bruno	Design-first, nativo de OpenAPI
Artefato inicial	Uma requisição que você pode enviar	Um contrato OpenAPI
Melhor para	Explorar e testar APIs existentes	Projetar APIs novas ou compartilhadas
Fonte da verdade	Coleção de requisições	Especificação OpenAPI
Revisão entre equipes	Depois que os endpoints existem	Antes do código do servidor
Design visual	Não é o foco padrão	Designer visual + editor de esquema
Risco de desvio	A coleção pode ficar atrás da API real	A especificação permanece como contrato
Git	Forte, com arquivos .bru em texto simples	Forte quando a especificação é sincronizada com Git

A decisão prática é simples:

• Se você está consumindo uma API existente, request-first funciona bem.
• Se você está definindo uma API para outras equipes, design-first tende a reduzir retrabalho.

Como o modelo request-first do Bruno funciona

Bruno armazena requisições como arquivos .bru em texto simples dentro de uma pasta do projeto. Isso permite versionar coleções com Git, revisar mudanças em PRs e manter o cliente de API próximo do código.

Esse modelo se encaixa bem em um fluxo de trabalho de API nativo de Git, especialmente quando o objetivo é testar endpoints existentes.

Use Bruno quando você precisa:

1. Explorar uma API em execução

   • Criar requisições rapidamente.
   • Inspecionar respostas.
   • Ajustar headers, query params e body.
   • Iterar até entender o comportamento real do serviço.

2. Versionar requisições com Git

   • Manter arquivos em texto simples.
   • Revisar mudanças em pull requests.
   • Evitar dependência de sincronização proprietária.

3. Executar testes básicos

   • Usar variáveis de ambiente.
   • Adicionar scripts pré e pós-requisição.
   • Criar asserções para respostas esperadas.

4. Evitar lock-in

   • Trabalhar com arquivos locais.
   • Manter controle sobre a coleção.

Um exemplo conceitual de fluxo request-first:

# 1. Criar uma coleção local
# 2. Adicionar uma requisição GET /users
# 3. Executar contra o ambiente local
# 4. Ajustar headers, tokens e parâmetros
# 5. Commitar os arquivos .bru no Git
git add api-collection/
git commit -m "Add user API requests"

Se seu trabalho é consumir, verificar ou depurar APIs já publicadas, request-first costuma ser o caminho mais direto. Esse ponto também aparece na comparação com plataformas mais amplas neste detalhamento da alternativa Bruno.

Onde request-first começa a limitar o fluxo

O atrito aparece quando a API ainda não existe ou quando várias equipes precisam concordar sobre o contrato antes da implementação.

1. Não há uma camada de design como fonte primária

Em ferramentas request-first, endpoints são representados como chamadas individuais. Isso é útil para testar, mas não substitui um modelo declarativo de:

• recursos;
• schemas;
• parâmetros;
• respostas;
• erros;
• autenticação;
• versionamento.

Projetar apenas com exemplos de requisição pode deixar lacunas. Exemplos mostram casos específicos, mas não impõem necessariamente a estrutura completa do contrato.

2. A coleção pode divergir da API real

Quando a coleção é a fonte da verdade, ela reflete o que alguém testou, não necessariamente o contrato atual da API.

Exemplo de problema comum:

{
  "id": "usr_123",
  "name": "Ana"
}

Depois, a API real passa a retornar:

{
  "id": "usr_123",
  "name": "Ana",
  "status": "active"
}

Se a coleção não for atualizada, o time pode não perceber imediatamente. Em um fluxo design-first, a mudança deveria começar no contrato:

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - status
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
            - active
            - inactive

Assim, a especificação OpenAPI continua sendo a referência para implementação, mocks, documentação e testes.

3. Revisão antes do código fica mais difícil

Revisar uma pasta de requisições mostra como alguém pretende chamar endpoints. Mas isso não é o mesmo que revisar um contrato completo antes do backend ser implementado.

Em uma revisão design-first, o PR pode responder perguntas como:

• O recurso está bem modelado?
• Os nomes dos campos são consistentes?
• Os status HTTP estão corretos?
• Os erros seguem um padrão?
• O contrato atende frontend, backend e documentação?
• Há impacto em clientes existentes?

Com request-first, essa revisão tende a acontecer mais tarde, quando parte da implementação já existe.

Quando design-first vence

Design-first é mais útil quando a API é um contrato compartilhado. Em vez de começar por uma requisição executável, você começa por uma especificação OpenAPI.

Use design-first em APIs greenfield

Quando a API ainda não existe, a especificação pode ser o primeiro artefato técnico.

Fluxo recomendado:

1. Definir recursos e operações
2. Modelar schemas de request e response
3. Revisar contrato com backend, frontend e produto
4. Gerar mocks ou documentação
5. Implementar backend contra a especificação
6. Validar a implementação com base no contrato

Exemplo mínimo de endpoint em OpenAPI:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Buscar usuário por ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Usuário encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Usuário não encontrado
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string

Use design-first em contratos multi-equipe

Quando backend e frontend trabalham em paralelo, o contrato reduz dependência entre times.

Exemplo de fluxo:

Backend + Frontend revisam OpenAPI
            ↓
Contrato aprovado
            ↓
Frontend usa mock baseado na especificação
            ↓
Backend implementa endpoints reais
            ↓
Testes validam se implementação segue o contrato

O frontend não precisa esperar o endpoint real ficar pronto para começar a integração.

Use design-first em APIs públicas

Para APIs públicas, documentação e estabilidade fazem parte do produto. Uma especificação mantida ajuda em:

• documentação de referência;
• mocks;
• SDKs;
• versionamento;
• comunicação de breaking changes;
• onboarding de desenvolvedores externos.

O ponto central: design-first vence quando a API precisa ser aprovada antes do código, não apenas testada depois que já está em produção.

Como aplicar design-first com Apidog e Modo Spec-First

Apidog é construído para um fluxo design-first. A ideia é manter a especificação OpenAPI como contrato principal, sem abrir mão de uma experiência visual e compatível com Git.

Você pode trabalhar de duas formas no mesmo projeto:

1. Designer visual

Use o designer visual para definir:

• endpoints;
• métodos HTTP;
• parâmetros;
• headers;
• bodies;
• schemas de resposta;
• componentes reutilizáveis;
• autenticação.

Esse modo é útil quando a equipe quer revisar o contrato sem editar YAML manualmente.

2. Modo Spec-First

Use o Modo Spec-First quando quiser editar o documento OpenAPI diretamente.

Exemplo de trabalho:

1. Abrir o projeto no Apidog
2. Entrar no Modo Spec-First
3. Editar o arquivo OpenAPI
4. Validar schemas, paths e responses
5. Sincronizar com Git
6. Abrir PR para revisão do contrato

O designer visual e o editor de especificação permanecem sincronizados. Isso permite que um engenheiro backend trabalhe no OpenAPI bruto enquanto outra pessoa revisa o design pela interface visual.

Sincronização Git bidirecional

O Modo Spec-First também suporta sincronização Git bidirecional. A especificação vive no repositório como um arquivo real, e as mudanças podem fluir entre o Git e o Apidog.

Fluxo prático:

# Exemplo de estrutura
api/
  openapi.yaml
src/
  server/
  client/

# Revisão normal via Git
git checkout -b api/update-user-contract
git add api/openapi.yaml
git commit -m "Update user API contract"
git push origin api/update-user-contract

Com isso, o design da API passa pelo mesmo processo de revisão do código: branch, commit, PR e aprovação.

A mecânica completa está na documentação do Modo Spec-First.

O resultado é um fluxo que cobre os dois lados:

• projetar o contrato antes da implementação;
• testar endpoints como cliente depois que eles estão ativos.

Para uma análise mais detalhada, veja spec-first vs design-first no Apidog.

Como escolher pela maturidade da equipe

Use o estágio da API como critério principal.

Equipe solo ou pequena

Se você consome principalmente APIs existentes, request-first pode ser suficiente.

Use Bruno quando:

• você precisa testar endpoints rapidamente;
• a API já está em execução;
• não há várias equipes dependendo do contrato;
• a coleção local versionada resolve o problema.

Equipe em crescimento

Quando outra equipe começa a depender dos seus endpoints, um contrato explícito passa a economizar tempo.

Considere design-first quando:

• frontend e backend precisam trabalhar em paralelo;
• mudanças de API precisam ser aprovadas antes da implementação;
• schemas precisam ser reutilizados;
• documentação precisa acompanhar o contrato.

Organização madura

Para APIs públicas ou muitas APIs internas, design-first tende a ser necessário.

A especificação passa a funcionar como:

• contrato;
• documentação;
• governança;
• base para mocks;
• referência para testes;
• material de onboarding.

A leitura prática é: equipes geralmente começam com request-first e evoluem para design-first conforme suas APIs deixam de ser apenas endpoints internos e passam a ser contratos compartilhados.

FAQ

Bruno é request-first ou design-first?

Bruno é request-first. Seu modelo central é compor, organizar e enviar requisições armazenadas como arquivos de texto simples. Isso é ideal para explorar e testar APIs existentes, mas não é focado em criar um contrato OpenAPI antes da implementação.

Posso fazer trabalho design-first no Bruno?

Não nativamente da mesma forma que uma ferramenta centrada em especificação. Bruno foca em requisições, não em um designer visual ou em um documento OpenAPI como fonte da verdade. Se você precisa definir e revisar um contrato antes do código, uma ferramenta design-first e nativa de OpenAPI se encaixa melhor.

Preciso abrir mão do Git para usar design-first?

Não. A propriedade nativa do Git também pode ser aplicada à especificação. O Modo Spec-First do Apidog mantém o documento OpenAPI no repositório com sincronização bidirecional, permitindo revisão por PRs e histórico versionado.