DEV Community

Cover image for Apidog에서 전역 파라미터 설정 방법 (모든 요청에 인증 헤더 자동 전송)
Rihpig
Rihpig

Posted on • Originally published at apidog.com

Apidog에서 전역 파라미터 설정 방법 (모든 요청에 인증 헤더 자동 전송)

프로젝트에 엔드포인트가 40개이고 모든 호출에 Authorization: Bearer ...와 X-Api-Version 헤더가 필요하다면, 요청마다 헤더를 수동으로 추가하지 마세요. 누락된 헤더 때문에 일부 경로에서만 발생하는 401 오류를 추적하는 대신, Apidog에서 프로젝트 기본값으로 한 번 정의해 모든 요청에 자동 적용할 수 있습니다.

지금 Apidog를 사용해 보세요

Apidog에서는 프로젝트 수준 헤더, 변수, 폴더 범위 사전 요청 스크립트를 조합해 공통 헤더를 관리할 수 있습니다. 이 글에서는 다음을 구현합니다.

  • 모든 요청에 Authorization과 X-Api-Version 자동 추가
  • 토큰을 {{token}} 변수로 분리
  • 실제 요청에 헤더가 포함됐는지 검증
  • 특정 폴더에만 헤더를 적용하는 대안 구성
  • CLI와 CI 실행에서도 동일한 환경 값 사용

변수 사용 방식이 익숙하지 않다면 Apidog에서 변수 마스터하기도 함께 참고하세요.

공통 헤더는 Apidog만의 개념은 아닙니다. MDN HTTP 헤더 참조에서 설명하듯, 헤더는 요청과 함께 전달되는 키/값 쌍입니다. Apidog는 이 값을 요청마다 반복 입력하지 않도록 프로젝트 수준에서 관리하게 해 줍니다.

“전역 매개변수”의 범위와 우선순위

Apidog의 전역 매개변수는 특정 엔드포인트가 아니라 프로젝트 전체에 적용되는 요청 매개변수입니다. 한 번 정의하면 일치하는 요청에 자동으로 첨부됩니다.

전역 매개변수는 다음 위치를 지원합니다.

  • 헤더: Authorization, X-Api-Version 같은 요청 헤더
  • 쿠키: 세션 쿠키
  • 쿼리: 모든 URL에 추가할 ?api_key= 같은 쿼리 매개변수
  • 바디: 모든 요청 본문에 포함할 필드

인증과 API 버전 관리에는 헤더를 사용하면 됩니다.

우선순위 규칙

전역 매개변수는 엔드포인트 수준 매개변수보다 우선순위가 낮습니다.

예를 들어 특정 요청에 자체 Authorization 헤더가 있다면, 해당 요청의 헤더가 사용되고 전역 Authorization 값은 적용되지 않습니다. 따라서 전역 매개변수는 강제 재정의가 아니라 프로젝트 기본값으로 사용하세요.

이 규칙 덕분에 대부분의 요청은 공통 토큰을 사용하면서, 일부 경로만 별도 토큰을 사용할 수 있습니다.

모든 요청에 전역 헤더 추가하기

목표는 다음 두 헤더를 모든 엔드포인트에 자동으로 적용하는 것입니다.

Authorization: Bearer {{token}}
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

1. 환경 관리 열기

프로젝트 오른쪽 상단에서 환경 관리를 엽니다.

여기서 프로젝트 전체에 적용할 매개변수를 위치별로 추가할 수 있습니다. 관련 동작은 Apidog 문서에서도 확인할 수 있습니다.

2. 헤더 위치 선택

인증 헤더를 추가할 것이므로 헤더를 선택합니다.

쿠키, 쿼리, 바디에 공통 값을 넣어야 하는 경우에도 같은 방식으로 해당 위치를 선택하면 됩니다.

3. Authorization 헤더 추가

첫 번째 전역 헤더를 다음과 같이 입력합니다.

항목 값
이름 Authorization
유형 문자열
기본값 Bearer {{token}}
설명 모든 인증된 엔드포인트에 대한 베어러 토큰

토큰을 직접 입력하지 않고 {{token}} 변수를 참조하는 것이 중요합니다.

4. X-Api-Version 헤더 추가

두 번째 전역 헤더를 추가합니다.

항목 값
이름 X-Api-Version
유형 문자열
기본값 2024-08-01
설명 모든 요청에 고정된 API 버전

5. 헤더 활성화 및 저장

각 행 오른쪽의 활성화 스위치를 켭니다.

이 스위치는 디버깅할 때 유용합니다. 전역 헤더를 삭제하지 않고도 잠시 비활성화할 수 있습니다. 설정을 저장하면, 엔드포인트에서 별도 값을 지정하지 않는 한 모든 요청에 두 헤더가 포함됩니다.

6. 실제 전송 여부 검증

설정만 보고 끝내지 말고 실제 요청을 확인하세요.

  1. 프로젝트에서 아무 요청이나 전송합니다.
  2. 응답 콘솔에서 실제 요청(Actual Request) 탭을 엽니다.
  3. 전송된 요청에 다음 헤더가 포함됐는지 확인합니다. 
GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

실제 요청 탭에서는 {{token}} 같은 변수가 해석된 최종 요청을 볼 수 있습니다. 헤더가 이 탭에 표시되면 실제로 전송된 것입니다.

토큰은 헤더에 직접 쓰지 말고 변수로 관리하기

다음처럼 토큰을 직접 헤더에 입력하는 방식은 피하세요.

Authorization: Bearer sk_live_7f3a9c2e1b8d4056
Enter fullscreen mode Exit fullscreen mode

대신 다음처럼 변수를 사용합니다.

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Bearer 인증 스키마는 RFC 6750에 정의되어 있으며, 서버가 Authorization 헤더를 처리하는 방식은 MDN Authorization 헤더 참조에서 확인할 수 있습니다.

token 변수 만들기

  1. 오른쪽 상단의 환경 아이콘(≡)을 클릭합니다.
  2. 전역 변수 섹션을 찾습니다.
  3. 이름이 token인 변수를 생성합니다.
  4. 변수 값에 실제 베어러 토큰을 입력합니다.
  5. 저장을 클릭합니다.

이제 요청 전송 시 다음 값이 해석됩니다.

Authorization: Bearer <실제 비밀>
Enter fullscreen mode Exit fullscreen mode

전역 매개변수는 헤더 형식을 관리하고, 변수는 비밀 값을 관리합니다. 즉, 다음 패턴을 기본으로 사용하면 됩니다.

전역 매개변수: Authorization = Bearer {{token}}
변수: token = 실제 토큰 값
Enter fullscreen mode Exit fullscreen mode

비밀 값과 환경 구성 분리에 대해서는 API 클라이언트 환경 및 비밀 관리도 참고할 수 있습니다.

환경별 토큰 전환

개발, 테스트, 프로덕션 환경은 일반적으로 서로 다른 서버와 토큰을 사용합니다.

각 환경에 서로 다른 token 값을 저장하고, ≡ 아이콘 옆의 환경 드롭다운에서 환경을 전환하세요. 예를 들어 샘플 환경 이름은 Local Mock일 수 있습니다.

전환 후에도 전역 헤더 정의는 그대로 유지됩니다.

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

변경되는 것은 현재 환경에서 {{token}}이 해석하는 실제 값뿐입니다.

베어러 토큰, API 키, OAuth 같은 인증 방식이 요청에 매핑되는 방식은 보안 체계 가이드에서 확인할 수 있습니다.

특정 폴더에만 헤더 적용하기

전역 매개변수는 프로젝트 전체에 적용됩니다. 하지만 /admin 경로에만 다음 헤더가 필요할 수 있습니다.

X-Admin-Scope: full
Enter fullscreen mode Exit fullscreen mode

Apidog에는 폴더 설정에서 헤더를 직접 추가하는 기본 UI가 없습니다. 대신 해당 폴더의 사전 요청 스크립트에 다음 코드를 추가합니다.

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });
Enter fullscreen mode Exit fullscreen mode

이 스크립트가 있는 폴더의 모든 요청은 X-Admin-Scope 헤더를 상속합니다. 폴더 밖의 요청에는 영향을 주지 않습니다.

이 방식은 프로젝트 전체에는 적용하면 안 되는 관리자 API, 파트너 API, 내부 서비스 API에 유용합니다. 스크립트 모델 전체는 Apidog의 사전 요청 및 사후 요청 스크립트 사용 방법에서 확인하세요.

어떤 방법을 선택해야 할까?

헤더의 적용 범위에 따라 선택하면 됩니다.

요구사항 권장 방법
모든 요청에 인증 헤더 또는 버전 헤더 적용 전역 매개변수의 헤더
토큰을 환경별로 교체하고 비밀을 분리 환경 변수 ({{token}})
특정 폴더에만 헤더 적용 폴더 수준 사전 요청 스크립트

구성 시 다음도 확인하세요.

  • 전역 헤더 이름이 중복되지 않는지 확인합니다.
  • 헤더 값은 문자열 유형으로 지정합니다.
  • 특정 엔드포인트가 같은 이름의 헤더를 정의했는지 확인합니다.
  • 전역 헤더가 보이지 않으면 실제 요청 탭에서 최종 요청을 먼저 확인합니다.

전역 매개변수, 환경 변수, 폴더 수준 사전 요청 스크립트에 대해서는 문서상 별도 요금제 제한이 명시되어 있지 않습니다.

Apidog CLI로 같은 설정을 CI에서 실행하기

전역 매개변수와 환경 변수는 GUI 요청에서만 동작하는 설정이 아닙니다. 저장된 테스트 시나리오를 Apidog CLI로 실행할 때도, 선택한 환경의 변수 값과 설정이 사용됩니다.

CLI를 설치하고 인증합니다.

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

특정 환경으로 저장된 시나리오를 실행합니다.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

주요 옵션은 다음과 같습니다.

  • -t: 테스트 시나리오 ID
  • -e: 환경 ID
  • -r: 리포터 형식 (cli, html, junit)

-e로 환경을 지정하면 해당 환경의 token 값이 사용됩니다. 따라서 GUI에서 설정한 다음 헤더도 CI 실행에서 같은 방식으로 해석됩니다.

Authorization: Bearer {{token}}
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

설치와 토큰 설정은 Apidog CLI 설치 가이드에서, GitHub Actions 연동은 GitHub Actions의 Apidog CLI에서 확인할 수 있습니다.

자주 묻는 질문

전역 매개변수가 엔드포인트의 헤더를 재정의하나요?

아니요. 엔드포인트 수준 헤더가 전역 매개변수보다 우선합니다.

특정 요청에 자체 Authorization 헤더가 있으면 그 값이 사용되고, 전역 Authorization 값은 해당 요청에 적용되지 않습니다.

토큰은 어디에 저장해야 하나요?

토큰을 헤더 기본값에 직접 넣지 말고 환경 변수 또는 전역 변수에 저장하세요.

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

실제 토큰은 token 변수에 저장합니다. 로그인 응답에서 토큰을 추출해 재사용해야 한다면 JSONPath를 사용하여 변수 추출하기를 참고하세요.

헤더가 실제로 전송됐는지 어떻게 확인하나요?

요청을 전송한 뒤 응답 콘솔의 실제 요청(Actual Request) 탭을 확인하세요.

여기에는 변수 값이 해석된 최종 요청이 표시됩니다. 해당 탭에 헤더가 있으면 실제 전송된 것입니다.

단일 폴더에만 기본 헤더를 추가할 수 있나요?

가능합니다. 다만 폴더 헤더 UI가 아니라 폴더의 사전 요청 스크립트를 사용해야 합니다.

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });
Enter fullscreen mode Exit fullscreen mode

전역 매개변수와 환경 변수는 유료 기능인가요?

문서에는 전역 매개변수, 환경 변수, 폴더 수준 사전 요청 스크립트에 대한 티어 제한이 명시되어 있지 않습니다.

마무리

Apidog에서 공통 헤더를 관리하는 기본 구성은 다음과 같습니다.

  1. 환경 관리에서 헤더를 전역 매개변수로 추가합니다.
  2. Authorization 값은 Bearer {{token}}으로 설정합니다.
  3. 실제 토큰은 환경 또는 전역 변수에 저장합니다.
  4. 실제 요청(Actual Request) 탭에서 최종 헤더를 검증합니다.
  5. 특정 폴더에만 필요한 헤더는 사전 요청 스크립트로 처리합니다.

프로젝트의 모든 엔드포인트를 수정하는 대신 한 번의 설정으로 공통 헤더를 적용할 수 있습니다. 직접 구성하려면 Apidog를 다운로드하고 첫 번째 전역 헤더부터 설정해 보세요.

Top comments (0)