[개발자 생산성 향상 시리즈 #6]🚀 개발 생산성 부스터! Postman으로 API 테스트 완전 정복

안녕하세요, 개발자 여러분! ✨ 개발자의 생산성을 높이는 도구/팁 시리즈, 벌써 6번째 시간입니다. 지난 시간에는 [효율적인 버전 관리를 위한 Git 고급 활용법]에 대해 알아보았는데요. 오늘은 백엔드 API를 개발하거나 프론트엔드에서 API를 연동할 때, 마치 든든한 지원군처럼 우리의 개발 속도와 안정성을 책임져 줄 API 테스트 도구에 대해 깊이 파헤쳐 보는 시간을 갖겠습니다. 그중에서도 가장 많은 사랑을 받는 Postman을 중심으로 핵심 기능과 활용 팁을 아낌없이 소개해 드릴게요! 😊

---

반응형

📜 개요: API 테스트, 왜 전문가의 도구가 필요할까요?

API 개발이나 연동 과정에서 테스트는 필수불가결한 단계입니다. API가 의도한 대로 정확히 동작하는지, 다양한 요청에 대해 올바른 응답을 주는지, 예외 상황은 잘 처리하는지 등을 꼼꼼히 확인해야 하죠. 물론 curl 같은 커맨드라인 도구나 간단한 스크립트로도 테스트할 수 있지만, 복잡한 요청이나 반복적인 테스트, 팀과의 협업에는 한계가 따릅니다. 😥

이때 Postman이나 Insomnia와 같은 GUI 기반 API 테스트 도구는 그야말로 빛을 발합니다! ✨ 직관적인 인터페이스로 요청을 쉽게 구성하고, 응답을 명확하게 확인할 수 있으며, 테스트 케이스를 체계적으로 관리하고 자동화하는 기능까지 제공하죠.

이번 6화에서는 다음과 같은 Postman의 핵심 기능과 이를 통해 어떻게 개발 생산성을 극대화할 수 있는지 자세히 알아보겠습니다.

• API 테스트 도구가 필요한 진짜 이유
• Postman 기본 사용법 (요청 보내고 응답 받기)
• 인증/권한 처리도 스마트하게!
• 환경 변수로 유연한 테스트 환경 구축하기
• 테스트 자동화로 반복 작업 줄이기
• 컬렉션으로 API 요청 묶음 관리하기

---

🤔 왜 API 테스트 도구가 필요할까요?

API 개발/연동 시 Postman과 같은 전문 도구를 사용해야 하는 이유는 명확합니다.

• 수동 테스트의 한계 극복: curl과 같은 CLI 도구나 임시 스크립트는 요청 파라미터가 많아지거나 인증 헤더 등이 복잡해지면 사용하기 번거롭고 실수하기 쉽습니다. GUI 도구는 직관적인 입력 필드를 제공하여 이런 어려움을 해소해 줍니다.
• 반복성과 효율성: 한 번 설정한 요청은 저장해두고 언제든 다시 실행할 수 있습니다. 또한, 유사한 요청을 복제하여 약간만 수정하는 것도 매우 간편하여 반복적인 테스트 작업 시간을 획기적으로 줄여줍니다.
• 협업 용이성: 잘 정리된 API 요청 명세(Collection)를 팀원들과 쉽게 공유하고, 동일한 환경에서 테스트를 진행할 수 있습니다. 이는 특히 프론트엔드와 백엔드 개발자 간의 원활한 소통과 협업을 돕습니다.

🛠️ 대표적인 API 테스트 도구: Postman 파헤치기!

Postman과 Insomnia는 현재 가장 인기 있는 API 테스트 도구입니다. Insomnia는 좀 더 가볍고 심플한 UI를 선호하는 개발자들에게 좋은 평가를 받고 있으며, 특히 GraphQL 테스트에 강점을 보이기도 합니다. 하지만 Postman은 방대한 기능, 풍부한 커뮤니티 자료, 강력한 협업 기능으로 오랫동안 시장을 선도해왔죠. 오늘은 Postman을 중심으로 살펴보겠습니다.

(Postman을 아직 설치하지 않으셨다면, 공식 웹사이트에서 쉽게 다운로드하여 설치할 수 있습니다. UI는 직관적이지만, 스크린샷과 함께 본다면 더욱 이해가 빠를 것입니다. 여기서는 텍스트로 주요 UI 요소를 설명드리겠습니다.)

1. 기본적인 요청 보내기 (GET, POST, PUT, DELETE 등 HTTP 메서드):
   • Postman을 실행하면 새 탭(New Tab)을 열 수 있습니다. 중앙 상단에는 HTTP 메서드(GET, POST 등)를 선택하는 드롭다운 메뉴와 요청을 보낼 URL을 입력하는 주소창이 있습니다.
   • GET 요청: 데이터를 조회할 때 사용합니다. URL을 입력하고 'Send' 버튼을 누르면 하단에 응답(Response)이 표시됩니다.
   • POST 요청: 새로운 리소스를 생성할 때 주로 사용합니다. 데이터를 서버로 전송해야 하므로 'Body' 탭에서 데이터의 형식(form-data, x-www-form-urlencoded, raw 등)을 선택하고 내용을 입력합니다. JSON 형식으로 데이터를 보낼 경우 'raw'를 선택하고 드롭다운에서 'JSON'을 선택합니다.
2. 요청 헤더(Headers), 파라미터(Params), 바디(Body) 설정 방법:
   • Params 탭: URL에 쿼리 스트링(?key1=value1&key2=value2)으로 전달될 파라미터를 Key-Value 형태로 입력할 수 있습니다. 여기에 입력하면 URL에 자동으로 반영됩니다.
   • Headers 탭: HTTP 요청 헤더를 설정합니다. Content-Type, Authorization 등 필요한 헤더 정보를 Key-Value 형태로 추가할 수 있습니다.
   • Body 탭: POST, PUT, PATCH 요청 시 서버로 전송할 데이터를 담는 부분입니다.
     • form-data: 파일이나 텍스트 데이터를 멀티파트 형식으로 보낼 때 사용합니다.
     • x-www-form-urlencoded: 간단한 텍스트 데이터를 Key-Value 쌍으로 인코딩하여 보냅니다.
     • raw: JSON, XML, Text, HTML 등 원시 텍스트 데이터를 보낼 때 사용합니다. 가장 흔하게 JSON 데이터를 보낼 때 사용되죠.
     • binary: 이미지, 오디오, 비디오 등 바이너리 파일을 직접 선택하여 보낼 때 사용합니다.
3. 인증 및 권한 처리 (API Key, Basic Auth, OAuth 2.0 등):
   • 많은 API가 보안을 위해 인증을 요구합니다. Postman의 'Authorization' 탭에서 다양한 인증 방식을 손쉽게 설정할 수 있습니다.
   • API Key: 주로 헤더나 쿼리 파라미터에 API 키를 추가하는 방식입니다. 'API Key' 타입을 선택하고 Key 이름, 값, 추가 위치(Header or Query Params)를 지정합니다.
   • Basic Auth: 사용자 이름과 비밀번호를 Base64로 인코딩하여 헤더에 추가하는 방식입니다. 'Basic Auth' 타입을 선택하고 Username과 Password를 입력하면 Postman이 자동으로 헤더를 생성해줍니다.
   • Bearer Token: OAuth 2.0 등에서 발급받은 액세스 토큰을 헤더에 Authorization: Bearer <token> 형태로 추가하는 방식입니다. 'Bearer Token' 타입을 선택하고 토큰 값을 입력합니다.
   • OAuth 2.0: 가장 복잡하지만 강력한 인증 방식입니다. Postman은 OAuth 2.0 인증 흐름을 도와주는 UI를 제공하여, 필요한 정보(Auth URL, Access Token URL, Client ID, Client Secret 등)를 입력하면 토큰을 쉽게 발급받을 수 있도록 지원합니다.
4. 환경 변수 활용 (개발, 스테이징, 운영 환경별 URL 등 관리):
   • 개발을 하다 보면 로컬 개발 환경, 테스트(스테이징) 환경, 실제 운영 환경 등 여러 환경에 API를 배포하게 됩니다. 각 환경마다 API 기본 URL이나 인증 토큰 등이 다를 수 있죠.
   • Postman의 'Environments' 기능을 사용하면 이런 환경별 변수를 효율적으로 관리할 수 있습니다.
   • 우측 상단의 눈 모양 아이콘(Environment quick look) 옆 드롭다운에서 'Manage Environments'를 선택하여 새 환경을 만들고, 변수 이름(예: baseURL, authToken)과 초기값/현재값을 설정합니다.
   • 요청 URL이나 헤더 값 등에 {{baseURL}}/users나 {{authToken}}처럼 중괄호 두 개로 감싸 변수를 사용하면, 선택된 환경에 따라 해당 값이 자동으로 치환됩니다. 정말 편리하죠! 🤩
5. API 테스트 자동화 기초 (테스트 스크립트 작성):
   • Postman은 요청을 보낸 후 응답을 검증하는 테스트 스크립트를 JavaScript로 작성할 수 있게 지원합니다. 'Tests' 탭에서 스크립트를 작성합니다.
   • 자주 사용되는 검증 코드 스니펫이 오른쪽에 제공되어 클릭만으로 쉽게 추가할 수 있습니다.
   • 예를 들어, 응답 상태 코드가 200인지, 응답 바디에 특정 JSON 키가 포함되어 있는지 등을 검증할 수 있습니다.
   • 이를 통해 단순 응답 확인을 넘어 API의 정합성을 자동으로 체크할 수 있어 개발 효율이 크게 향상됩니다.
6. 컬렉션(Collection) 또는 워크스페이스(Workspace) 활용:
   • 컬렉션(Collections): 관련된 API 요청들을 하나의 그룹으로 묶어 관리하는 기능입니다. 마치 폴더처럼 API들을 기능별, 버전별로 정리할 수 있습니다. 컬렉션 단위로 테스트를 실행하거나, 환경 변수를 설정하고, 문서를 생성하거나, 팀원들과 공유할 수 있습니다. 왼쪽 사이드바의 'Collections' 탭에서 생성하고 관리합니다.
   • 워크스페이스(Workspaces): 개인 작업 공간 또는 팀 협업 공간을 제공합니다. 여러 컬렉션, 환경, 모니터 등을 워크스페이스 단위로 관리하여 프로젝트별로 작업을 분리하거나 팀원들과 실시간으로 공유하며 협업할 수 있습니다.

---

🔧 예시/활용법: Postman 실제 사용 모습 엿보기

말로만 설명하면 감이 잘 안 올 수 있으니, 간단한 예시를 통해 Postman 사용법을 단계별로 살펴보겠습니다. (실제 Postman 화면을 상상하며 따라와 주세요!)

Postman 화면 구성 (텍스트 설명):

• 왼쪽 사이드바: History, Collections, APIs, Environments 등이 탭으로 구성되어 있습니다. 여기서 컬렉션을 만들고 요청을 저장, 관리합니다.
• 상단: 새 탭 열기(+), HTTP 메서드 선택(GET, POST 등), URL 입력창, Send 버튼 등이 위치합니다.
• 중앙 요청(Request) 영역: Params, Authorization, Headers, Body, Pre-request Script, Tests 탭들이 있어 요청의 세부 사항을 설정합니다.
• 하단 응답(Response) 영역: Send 버튼을 누르면 서버로부터 받은 응답이 표시됩니다. Body, Cookies, Headers, Test Results 탭으로 나누어 상세 정보를 확인할 수 있습니다.

1. 간단한 REST API에 GET 요청 보내기:

공개된 테스트 API인 https://jsonplaceholder.typicode.com/users/1 를 사용해 보겠습니다.

1. Postman에서 새 탭을 엽니다.
2. HTTP 메서드를 GET으로 선택합니다 (기본값).
3. URL 입력창에 https://jsonplaceholder.typicode.com/users/1 을 입력합니다.
4. 'Send' 버튼을 클릭합니다.
5. 하단 응답(Response) 영역의 'Body' 탭에서 사용자 1의 정보가 JSON 형태로 표시되는 것을 확인할 수 있습니다. 'Status'에는 200 OK가 표시될 것입니다.

2. POST 요청으로 데이터 생성하기 (가상 시나리오):

https://jsonplaceholder.typicode.com/posts 에 새 게시물을 등록한다고 가정해 봅시다.

1. 새 탭을 엽니다.
2. HTTP 메서드를 POST로 변경합니다.
3. URL 입력창에 https://jsonplaceholder.typicode.com/posts 를 입력합니다.
4. 'Body' 탭을 선택합니다.
5. 데이터 형식으로 raw를 선택하고, 오른쪽 드롭다운에서 JSON을 선택합니다.
6. 입력창에 다음과 같은 JSON 데이터를 입력합니다:

   {
       "title": "My New Post",
       "body": "This is the content of my new post.",
       "userId": 1
   }
   

7. 'Headers' 탭으로 이동하여 Content-Type 헤더가 application/json; charset=utf-8 등으로 자동으로 설정되었는지 확인하거나, 필요시 직접 추가합니다.
8. 'Send' 버튼을 클릭합니다.
9. 응답 Body에 방금 생성한 데이터와 함께 id 필드가 추가되어 반환되는 것을 볼 수 있습니다 (예: 201 Created).

3. 환경 변수 설정하고 사용하는 예시:

1. 오른쪽 상단 눈 모양 아이콘 옆 드롭다운에서 'Add'를 클릭하여 새 환경(Environment)을 만듭니다. 이름을 'My Test Env'로 지정합니다.
2. 'VARIABLE'에 baseURL, 'INITIAL VALUE'와 'CURRENT VALUE'에 https://jsonplaceholder.typicode.com 을 입력하고 저장합니다.
3. 다시 눈 모양 아이콘 옆 드롭다운에서 방금 만든 'My Test Env'를 선택하여 활성화합니다.
4. GET 요청 예시의 URL을 {{baseURL}}/users/1 로 수정하고 'Send'를 누릅니다.
5. 여전히 동일한 응답을 받는다면 환경 변수가 잘 적용된 것입니다! 이제 baseURL이 변경되어도 환경 설정만 바꿔주면 됩니다.

4. 응답 코드를 확인하는 간단한 테스트 스크립트 예시:

위 GET 요청 예시에서 응답 상태 코드가 200인지 확인하는 테스트를 추가해 봅시다.

1. GET 요청 ({{baseURL}}/users/1) 탭에서 'Tests' 탭을 선택합니다.
2. 오른쪽 'SNIPPETS'에서 'Status code: Code is 200'을 클릭하면 아래와 같은 스크립트가 자동으로 입력됩니다.

   pm.test("Status code is 200", function () {
       pm.response.to.have.status(200);
   });
   

   다시 'Send' 버튼을 누릅니다.
3. 하단 응답 영역의 'Test Results' 탭을 보면 'Status code is 200' 테스트가 PASS 되었음을 확인할 수 있습니다. 만약 API가 다른 상태 코드를 반환한다면 FAIL로 표시될 것입니다.

---

🎉 마무리 및 다음 화 예고

지금까지 API 테스트 도구의 필요성과 Postman의 핵심 기능, 그리고 간단한 활용 예시를 살펴보았습니다. Postman을 사용하면 API 요청을 체계적으로 관리하고, 다양한 인증 방식과 환경 변수를 손쉽게 처리하며, 테스트 자동화를 통해 개발 및 협업 생산성을 크게 향상시킬 수 있습니다. 든든한 API 테스트 파트너, Postman과 함께라면 API 개발 및 연동 작업이 훨씬 수월해질 거예요! 💪

오늘 소개해 드린 기능 외에도 Postman에는 Mock 서버, 모니터링, API 문서 자동 생성 등 더욱 강력한 기능들이 많으니, 직접 사용해보시면서 탐험해 보시길 적극 추천합니다.

 

다음 개발자의 생산성을 높이는 도구/팁 시리즈 7화에서는 "API 명세, 더 이상 고통받지 말자! 문서화 도구의 중요성과 사용법 (Swagger/OpenAPI 중심으로)" 라는 주제로 찾아뵙겠습니다. 잘 작성된 API 문서는 협업의 윤활유이자 프로젝트의 품질을 높이는 핵심 요소인데요. 다음 시간도 많이 기대해주세요! 감사합니다. 🙏