Rihpig

Posted on Jun 2 • Originally published at apidog.com

브루노 Request-First 방식인가? 디자인 우선 도구가 필요할 때

Bruno는 요청 중심(request-first) 도구입니다. HTTP 요청을 작성하고, 구성하고, 보내는 데 초점을 둡니다. 컬렉션을 만들고, 요청을 추가하고, .bru 파일로 저장하고, 실행한 뒤 Git에서 버전 관리합니다. 이 모델은 빠르고 Git 친화적이며, 이미 존재하는 API를 탐색하고 검증할 때 특히 효과적입니다.

지금 Apidog를 사용해 보세요

하지만 요청 중심(request-first)과 설계 중심(design-first)은 서로 다른 문제를 해결합니다.

요청 중심: 이 엔드포인트를 어떻게 호출할 것인가?
설계 중심: 이 엔드포인트는 구현 전에 어떤 계약을 가져야 하는가?

새 API를 만들거나 여러 팀이 같은 API에 의존하기 시작하면 이 차이가 중요해집니다. 이 글에서는 Bruno의 요청 중심 모델이 어디에 적합한지, 그리고 OpenAPI 기반 설계 중심 워크플로가 언제 더 나은 선택이 되는지 정리합니다.

요청 중심(Request-first) vs 설계 중심(Design-first)

두 방식은 경쟁 관계라기보다 API 수명 주기의 다른 출발점입니다.

차원	요청 중심 (Bruno)	설계 중심 (OpenAPI 기반)
시작 아티팩트	보낼 수 있는 요청	계약(OpenAPI 사양)
가장 적합한 경우	기존 API 탐색 및 테스트	코드 작성 전 새/공유 API 설계
진실의 원천	요청 컬렉션	OpenAPI 사양
팀 간 검토	엔드포인트가 존재한 후	서버 코드 작성 전
시각적 디자인 표면	기본적으로 없음	시각적 디자이너 + 스키마 편집기
불일치 위험	컬렉션이 실제 API보다 뒤처질 수 있음	사양이 단일 계약으로 유지됨
Git 통합	강력함: 평문 `.bru` 파일	사양을 Git과 동기화하면 강력함

선택 기준은 간단합니다.

이미 존재하는 API를 호출하고 테스트한다면 요청 중심이 빠릅니다.
아직 API를 정의 중이고 여러 팀이 합의해야 한다면 설계 중심이 유리합니다.

Bruno의 요청 중심 모델

Bruno는 요청을 사용자가 소유한 폴더에 평문 .bru 파일로 저장합니다. 필수 클라우드 계정, 독점 동기화, 기본 활성화된 원격 측정 없이 로컬 우선 방식으로 동작합니다.

API 클라이언트도 코드베이스처럼 Git에서 관리하고 싶은 개발자에게 이 방식은 큰 장점입니다. 이런 특성은 많은 팀이 채택한 Git-native API 워크플로의 핵심이기도 합니다.

Bruno가 잘 맞는 작업은 다음과 같습니다.

기존 API 탐색

실행 중인 서비스에 요청을 보내고 응답을 확인하며 빠르게 반복할 수 있습니다.
로컬 우선 + Git 친화적 관리

.bru 파일은 읽기 쉬운 평문이므로 diff와 merge가 비교적 명확합니다. 요청 변경 사항도 코드와 같은 PR에서 검토할 수 있습니다.
스크립팅 및 테스트

요청 전후 스크립트, 어설션, 환경 변수를 통해 일상적인 API 테스트를 처리할 수 있습니다.
낮은 종속성

파일은 사용자가 소유하고, 형식은 개방적입니다.

즉, 작업의 핵심이 이미 존재하는 API를 사용하고 검증하는 것이라면 요청 중심 방식은 가장 직접적인 선택입니다. 더 넓은 플랫폼 관점의 비교는 Bruno 대안 분석에서도 다룬 바 있습니다.

설계 또는 계약 계층이 없을 때 생기는 문제

API가 아직 존재하지 않거나 여러 팀이 API 형태에 합의해야 하는 순간, 요청 중심 모델의 한계가 드러납니다.

1. 시각적 API 디자인 표면이 부족함

요청 중심 도구는 엔드포인트를 “요청 예시”로 표현합니다. 하지만 API 설계에는 다음과 같은 요소가 필요합니다.

리소스 구조
요청/응답 스키마
오류 모델
재사용 가능한 컴포넌트
인증 방식
버전 정책

요청 예시는 빠르게 호출해 보기에는 좋지만, 구조를 강제하지는 않습니다. 백엔드 리더, 프론트엔드 개발자, 제품 엔지니어가 구현 전에 동일한 계약을 검토하기에는 부족할 수 있습니다.

2. 계약 불일치(Contract drift)가 발생하기 쉬움

컬렉션이 진실의 원천이면 컬렉션은 “누군가 이미 호출해 본 요청”만 반영합니다.

실제 API는 다음처럼 바뀔 수 있습니다.

GET /users?status=active

이후 서버에서 status 값이 변경되거나, 새 필드가 추가되거나, 특정 파라미터가 deprecated될 수 있습니다. 하지만 요청 컬렉션은 테스트가 실패하기 전까지 뒤처질 수 있습니다.

설계 중심 워크플로는 순서를 반대로 둡니다.

OpenAPI 사양을 계약으로 정의
구현이 계약을 따르는지 검증
문서, mock, 테스트를 같은 계약에서 생성

3. 코드 작성 전 검토가 어려움

요청 폴더를 검토하면 “현재 엔드포인트를 어떻게 호출하는지”는 알 수 있습니다. 하지만 구현 전에 다음을 검토하기에는 한계가 있습니다.

이 리소스 모델이 적절한가?
응답 스키마가 클라이언트 요구사항을 충족하는가?
오류 응답이 일관적인가?
이 변경이 breaking change인가?

설계 중심에서는 OpenAPI 사양 자체가 리뷰 대상이 됩니다. 서버 코드 한 줄을 작성하기 전에 API 계약을 PR로 검토할 수 있습니다.

이것이 Bruno가 나쁜 도구라는 뜻은 아닙니다. 단지 Bruno는 요청 중심 도구이며, 계약 설계가 필요한 작업에는 다른 도구가 더 적합할 수 있다는 의미입니다.

설계 중심(Design-first)이 더 적합한 경우

설계 중심 방식은 특히 다음 상황에서 효과적입니다.

1. 그린필드(Greenfield) API

아직 API가 존재하지 않는다면 사양 자체가 설계 문서가 됩니다.

예를 들어 사용자 생성 API를 먼저 OpenAPI로 정의할 수 있습니다.

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string

이 계약에서 다음을 생성하거나 연결할 수 있습니다.

mock API
서버 스텁
API 문서
클라이언트 SDK
계약 기반 테스트

2. 여러 팀이 하나의 API에 의존하는 경우

백엔드 팀과 프론트엔드 팀, 모바일 팀이 같은 API에 의존한다면 OpenAPI 사양은 합의서 역할을 합니다.

실무 흐름은 다음처럼 가져갈 수 있습니다.

API 사양 초안 작성
프론트엔드/모바일/백엔드가 스키마 검토
계약 승인
mock API로 클라이언트 개발 시작
백엔드는 같은 계약을 기준으로 구현
구현 결과를 계약과 비교

이렇게 하면 백엔드 구현이 끝날 때까지 클라이언트 팀이 기다릴 필요가 줄어듭니다.

3. 공개 API

외부 개발자가 사용하는 API라면 문서와 안정성이 곧 제품 품질입니다.

공개 API에서는 다음이 중요합니다.

명확한 요청/응답 스키마
버전 관리
breaking change 관리
생성 가능한 참조 문서
일관적인 오류 응답
변경 이력 추적

잘 관리된 OpenAPI 계약은 이 모든 것의 기반이 됩니다.

공통점은 명확합니다. 설계 중심은 API가 출시 후 탐색할 서비스가 아니라, 코드 작성 전에 합의해야 하는 공유 인터페이스일 때 더 강력합니다.

Apidog의 설계 중심(Design-first) 및 사양 우선(Spec-First) 모드

Apidog는 설계 중심 워크플로를 지원합니다. 동시에 OpenAPI 기반의 Git 친화적인 작업 방식을 유지할 수 있습니다.

Apidog에서는 같은 프로젝트 안에서 두 가지 방식으로 작업할 수 있습니다.

1. 시각적 디자이너로 API 설계

YAML을 직접 작성하지 않고도 다음을 정의할 수 있습니다.

엔드포인트
요청 파라미터
요청 본문
응답 스키마
재사용 가능한 컴포넌트
인증 설정

이는 “설계 중심”이라고 할 때 많은 팀이 기대하는 방식입니다. API 구조를 시각적으로 보고 수정할 수 있어 비전문가와 협업하기도 쉽습니다.

2. 사양 우선(Spec-First) 모드로 OpenAPI 직접 작성

OpenAPI 문서를 진실의 원천으로 삼고 싶다면 사양 우선 모드를 사용할 수 있습니다. 이 모드에서는 OpenAPI를 직접 편집하며 계약을 관리합니다.

예를 들어 백엔드 엔지니어는 원시 OpenAPI를 편집하고, 제품 엔지니어는 시각적 캔버스에서 같은 계약을 확인할 수 있습니다. 두 방식은 동기화되므로 같은 API 계약을 기준으로 작업할 수 있습니다.

사양 우선 모드는 양방향 Git 동기화도 지원합니다. 즉, OpenAPI 사양을 저장소의 실제 파일로 관리하고, 변경 사항을 양방향으로 반영할 수 있습니다.

실무에서는 다음 흐름을 만들 수 있습니다.

OpenAPI 사양 수정
        ↓
Git 저장소에 커밋
        ↓
Pull Request 생성
        ↓
팀 리뷰
        ↓
Apidog 프로젝트와 동기화
        ↓
mock, 문서, 테스트에 반영

이 방식은 Bruno 사용자가 중요하게 여기는 Git-native 속성을 요청 컬렉션이 아니라 API 계약에 적용합니다. 자세한 내용은 사양 우선 모드 문서를 참고하세요.

결과적으로 하나의 워크플로에서 두 질문을 모두 다룰 수 있습니다.

구현 전: 계약을 먼저 설계
구현 후: 요청 중심 클라이언트처럼 테스트

이 두 모델이 만나는 지점은 Apidog의 사양 우선(spec-first) 대 설계 중심(design-first)에서 더 자세히 볼 수 있습니다.

팀 성숙도에 따른 선택 기준

도구를 고를 때는 취향보다 API의 수명 주기를 기준으로 판단하는 것이 좋습니다.

1. 단독 개발자 또는 소규모 팀

주로 외부 API를 호출하거나 기존 내부 API를 테스트한다면 요청 중심 도구로 충분합니다.

적합한 경우:

API가 이미 존재함
계약 리뷰가 필요하지 않음
빠른 요청 실행이 중요함
Git에서 요청 파일을 관리하고 싶음

이 경우 Bruno의 로컬 우선 모델은 가볍고 방해가 적습니다.

2. 자체 API를 출시하는 성장 중인 팀

두 번째 팀이 API에 의존하기 시작하면 상황이 달라집니다.

다음 신호가 보이면 계약 중심으로 전환할 시점입니다.

프론트엔드가 백엔드 완료를 기다림
API 변경으로 통합 버그가 자주 발생함
요청/응답 스키마가 문서와 다름
리뷰가 코드 구현 이후에만 이루어짐
mock API가 필요함

이 단계에서는 명시적인 OpenAPI 계약이 리뷰 주기와 통합 오류를 줄이는 데 도움이 됩니다.

3. 공개 API 또는 많은 내부 API를 운영하는 조직

공개 API나 대규모 내부 API를 운영한다면 설계 중심은 사실상 필수에 가깝습니다.

이 단계에서 OpenAPI 사양은 다음 역할을 동시에 수행합니다.

거버넌스 기준
문서 소스
온보딩 자료
변경 관리 기준
mock 및 테스트 기반
클라이언트/서버 생성 입력

Git 동기화가 가능한 OpenAPI 기반 도구를 사용하면 이 계약을 투명하게 관리할 수 있습니다.

실무 의사결정 체크리스트

아래 질문으로 현재 팀에 맞는 방식을 빠르게 판단할 수 있습니다.

Q1. API가 이미 구현되어 있는가?
  ├─ 예 → 요청 중심 도구가 적합할 가능성이 높음
  └─ 아니요 → 설계 중심 검토

Q2. 둘 이상의 팀이 이 API에 의존하는가?
  ├─ 예 → OpenAPI 계약 필요
  └─ 아니요 → 요청 중심으로 시작 가능

Q3. 구현 전에 API 리뷰가 필요한가?
  ├─ 예 → 설계 중심 필요
  └─ 아니요 → 요청 중심 가능

Q4. mock, 문서, 테스트를 같은 계약에서 생성하고 싶은가?
  ├─ 예 → 설계 중심 / 사양 우선 적합
  └─ 아니요 → 요청 중심으로 충분할 수 있음

Q5. Git에서 API 변경을 PR로 검토해야 하는가?
  ├─ 예 → Git 동기화 가능한 OpenAPI 워크플로 고려
  └─ 아니요 → 로컬 요청 컬렉션으로도 충분

정리하면 다음과 같습니다.

API를 호출하고 검증하는 작업: Bruno 같은 요청 중심 도구가 적합
API를 정의하고 합의하는 작업: OpenAPI 기반 설계 중심 도구가 적합
Git-native 특성을 유지하면서 계약을 관리해야 하는 작업: 사양 우선 + Git 동기화 워크플로가 적합

자주 묻는 질문

Bruno는 요청 중심(request-first)인가요, 설계 중심(design-first)인가요?

Bruno는 요청 중심(request-first)입니다. 핵심 모델은 평문 파일로 저장된 요청을 작성하고, 구성하고, 보내는 것입니다. 이미 존재하는 API를 탐색하고 테스트하는 데 적합하며, API 구현 전에 OpenAPI 계약을 작성하는 데 초점을 둔 도구는 아닙니다.

Bruno에서 설계 중심(design-first) 작업을 할 수 있나요?

사양 중심 도구가 제공하는 방식으로는 기본적으로 어렵습니다. Bruno는 시각적 디자이너나 OpenAPI 문서를 진실의 원천으로 삼기보다 요청 컬렉션에 초점을 둡니다.

코드 작성 전에 계약을 정의하고 검토해야 한다면 OpenAPI 기반 설계 중심 도구가 더 적합합니다.

설계 중심으로 가면 Git 친화성을 포기해야 하나요?

아니요. Git-native 속성은 요청 파일뿐 아니라 OpenAPI 사양에도 적용할 수 있습니다.

즉, 다음과 같은 워크플로가 가능합니다.

저장소에 평문 OpenAPI 파일 보관
변경 사항을 diff로 확인
PR로 API 계약 리뷰
승인 후 문서, mock, 테스트에 반영

Apidog의 사양 우선(Spec-First) 모드는 양방향 동기화를 통해 OpenAPI 문서를 저장소에 유지할 수 있으므로, 설계 중심이 Git을 포기한다는 의미는 아닙니다.

DEV Community