Postman은 개발자, API 테스터, 기술 문서 작성자, DevOps 팀이 API 개발을 테스트하고 문서화하며 협업할 때 사용하는 플랫폼입니다. HTTP, GraphQL, gRPC 등 다양한 형태의 API 요청을 손쉽게 만들고, 응답을 확인하며, API 요청들을 컬렉션 형태로 구성해 협업과 자동화를 지원합니다.

API 테스트 과정에서 반복 작업을 수행하는 일은 스트레스도 크고 시간이 많이 소요됩니다. 특히 Postman에서 새 인증 토큰을 받아 복사해서 붙여넣는 작업은 매우 반복적입니다. Postman 스크립트를 사용하면 인증 토큰을 자동으로 저장하고 재사용할 수 있어 이러한 반복 작업을 줄일 수 있습니다.

이 가이드를 따라 해보려면 다음이 필요합니다:

• Postman API 클라이언트가 설치된 컴퓨터
• Postman으로 API 요청을 만들어본 경험
• JWT 인증을 사용하는 백엔드 애플리케이션과 해당 API 문서

만약 백엔드 애플리케이션이 없다면, 제가 GitHub에 올려 둔 예제(orimdominic/freeCodeCamp-postman-api-jwt)를 클론해서 사용할 수 있습니다.

이 글을 다 읽고 나면, Postman에서 인증 토큰을 발급 / 저장 / 재사용하는 과정을 훨씬 단순화할 수 있습니다. 또한 Postman의 다른 테스트 자동화 작업에도 활용할 수 있는 실용적인 스크립트 개념을 익히게 될 것입니다.

목차

• Postman 스크립트란?
• JWT 인증 과정을 단순화하는 방법
• 인증 요청으로 토큰 받아오기
• Postman 스크립트로 토큰을 변수에 저장하기
• API 요청에서 변수 사용하기
• 다음 단계

Postman 스크립트란?

Postman 스크립트는 Postman API 클라이언트 내부에서 실행되는 JavaScript 코드로, API 테스트 워크플로우를 자동화하고 확장하는 데 사용합니다. 스크립트는 요청 전(pre-request)과 요청 후(post-response)에 실행되도록 추가할 수 있습니다. 스크립트를 사용하면 다음과 같은 작업이 가능합니다:

• API 요청 데이터를 처리하는 로직 추가
• API 응답에 대한 테스트(assertion) 작성
• API 엔드포인트 자동화 테스트 실행

Postman의 Scripts 탭에서 스크립트를 확인할 수 있습니다. Pre-request 탭은 요청이 실행되기 전에, Post-response 탭은 응답이 온 뒤에 실행됩니다.

JWT 인증 과정을 단순화하는 방법

이번 튜토리얼은 다음과 같은 순서대로 진행됩니다:

• 인증하여 토큰 발급받기
• 스크립트를 사용해 토큰을 컬렉션 변수에 저장하기
• API 요청에서 해당 변수를 사용하기

인증하여 토큰 발급받기

다음과 같은 순서대로 따라해보세요:

1. 백엔드 애플리케이션을 실행하고 정상적으로 동작하는지 확인합니다.
2. Postman을 열고 JWT를 발급받는 로그인(sign-in) 요청으로 이동합니다.
3. 로그인 엔드포인트에 API 요청을 보내고 JSON 응답 구조를 확인합니다.

위 이미지에서 하이라이트된 부분은 로그인 요청이 성공했을 때 반환되는 JSON 응답을 보여줍니다. 이 응답 스키마에서 인증에 사용할 토큰은 data.token 필드에 포함되어 있습니다. 이제 이 토큰을 Postman 스크립트를 사용해 변수로 저장한 뒤, 인증이 필요한 요청의 Authorization 헤더에서 해당 변수를 사용하게 될 것입니다.

스크립트를 사용해 토큰을 컬렉션 변수에 저장하기

Postman에서 Body 탭 옆에 있는 Scripts 탭을 클릭합니다. 만약 Postman 창이 작게 표시되어 있다면, 해당 탭이 드롭다운 메뉴 안에 있을 수 있으니 펼쳐서 확인합니다. 다음으로 Post-response 탭을 선택합니다. 오른쪽의 텍스트 영역에 응답에서 인증 토큰을 추출해 Postman 변수에 저장하는 스크립트를 작성하게 됩니다. 아래 JavaScript 코드를 복사해 이 텍스트 영역에 붙여 넣습니다.

if (pm.response.code == 200) {
    const token = pm.response.json().data.token
    pm.collectionVariables.set("auth_token", token)
}

Postman 스크립트에서는 pm 식별자를 사용해 Postman 환경의 정보에 접근하고 값을 수정합니다. 위 스크립트는 먼저 응답 상태 코드가 200인지 확인해 요청이 성공했는지 확인합니다.

조건문 내부에서는 pm.response.json().data.token을 사용해 JSON 응답에서 인증 토큰을 가져오고, 이를 auth_token이라는 컬렉션 변수에 저장합니다. 만약 auth_token 변수가 없다면 새로 생성되고, 이미 존재한다면 기존 값이 새 토큰 값으로 덮어씁니다.

토큰이 변수에 정상적으로 저장되었는지 확인하려면, 위 스크린샷 기준으로 먼저 컬렉션 이름(1)을 클릭한 뒤 Variables 탭(2)을 선택합니다. 이후에는 인증 토큰을 매번 복사해 Authorization 헤더에 붙여넣을 필요 없이, Authorization 헤더에서 auth_token 변수를 그대로 사용할 수 있습니다.

API 요청에서 해당 변수를 사용하기

Authorization 헤더에서 컬렉션 변수를 사용할 때는 {{auth_token}}처럼 중괄호 두 개로 감싸서 참조합니다. 이렇게 설정해두면, API 요청을 보낼 때 Postman이 {{auth_token}}에 저장된 값을 자동으로 Authorization 헤더에 넣어 사용합니다.

또 다른 인증 요청으로 인해 auth_token 값이 갱신되더라도, 새로운 토큰을 직접 복사해서 붙여넣을 필요는 없습니다. Post-response 탭에 작성한 스크립트가 자동으로 auth_token 값을 업데이트해 주기 때문에, 이후에도 API 요청을 문제없이 계속 보낼 수 있습니다. 더 이상 반복적인 복사 및 붙여넣기 작업을 할 필요가 없습니다. 즉, DRY (Don’t Repeat Yourself) 원칙을 지킬 수 있습니다.

다음 단계

이번 튜토리얼에서는 Postman 스크립트를 사용해 환경 변수를 설정하고, 인증 토큰을 자동으로 저장 및 재사용하는 방법을 배웠습니다.

API 테스트에 대한 더 많은 예제와 assertion 작성 방법을 알고 싶다면, Postman에서 제공하는 Test API Functionality and Performance in Postman 가이드를 참고하면 도움이 됩니다.

웹 개발에서 REST API는 클라이언트와 서버 간 통신을 원활하게 하는 중요한 역할을 합니다.

여기서 클라이언트는 프론트엔드, 서버는 백엔드라고 생각할 수 있습니다.

클라이언트(프론트엔드)와 서버(백엔드)는 서로 직접적으로 호출하기보다는, Application Programming Interface (API)라 불리는 중간자 역할의 인터페이스를 사용합니다.

API는 클라이언트-서버 통신 간 중요한 역할을 하므로, 항상 잘 생각해서 모범사례의 API를 설계해야 합니다. 그래야만 개발자들이 유지보수하기 쉽고, 사용하기 좋을 뿐만이 아니라, 사용하는 동안 문제를 일으키지 않습니다.

이 자료에서는 REST API를 만들기 위한 9가지 모범사례들을 소개할 예정입니다. 잘 따라온다면 여러분들은 사용자들이 사용하기 쉽고, 강력한 API들을 만들 수 있을 것입니다.

그 전에 앞서, REST API란 무엇일까요? REST는 Representational State Transfer의 약자로 해석하면 원하는 리소스를 현재 상태에 걸맞은 형태로 전송하는 것입니다. REST는 2000년에 Roy Fielding이 웹을 위해 디자인한 소프트웨어 아키텍처 형식입니다.

API(Application Programming Interface)는 Restful이라는 REST 디자인 원칙을 따릅니다.

간단히 말하자면, REST API는 두 컴퓨터가 HTTP(Hypertext Transfer Protocol)를 통해 통신할 때, 같은 형식에 맞춰 통신하도록 합니다.

REST API 디자인을 위한 모범사례

1. 데이터를 보내거나 받을 때 JSON 포맷을 사용하세요

예전에는 API 요청을 보내거나 받을 때 XML이나 HTML을 사용했었지만, 최근에는 JSON(JavaScript Object Notation)을 사용하는 것이 추세입니다.

XML은 사용할 때 데이터를 인코딩/디코딩하는 게 번거로울 때가 많아 여러 프레임워크에서 지원하지 않는 경우가 많습니다.

JavaScript는 API를 받아올 때 JSON을 사용하도록 만들어져 있기 때문에 JSON으로 파싱하는 내장 메소드를 가지고 있습니다. Python이나 PHP 같은 다른 프로그래밍 언어들도 요즘은 JSON으로 파싱하거나 데이터를 다룰 수 있는 메소드들을 지원합니다. (예를 들어, Python의 json.loads()나 json.dumps()가 있습니다.)

클라이언트 단(Client-side)에서 JSON 데이터를 정확하게 해석하도록 보장하기 위해서는 요청하는 동안 응답 헤더(Response header)에서 Content-Type 타입을 application/json으로 지정해야 합니다.

반대로 다수의 서버 단(Server-side) 프레임워크들에서는 Content-Type을 자동으로 할당합니다. (예를 들어, Express는 express.json()가 그 기능을 합니다. body-parser 라는 NPM의 패키지도 같은 기능을 합니다.)

2. 엔드포인트에서는 동사 대신 명사를 사용하세요

REST API를 설계할 때는 엔드포인트 주소에 동사를 사용하지 마세요. 이때는 명사를 사용해서 각 엔드포인트들이 무슨 일을 하는지 명시해야 합니다.

HTTP 메소드들이 이미 GET, PUT, PATCH, DELETE라는 동작을 (Create, Read, Update, Delete) 동사의 형태로 나타내기 때문입니다.

GET, POST, PUT, PATCH, DELETE는 가장 주로 쓰이는 HTTP 동사들이고, COPY, PURGE, LINK, UNLINK 등과 같은 다른 것들도 있습니다.

따라서 엔드포인트 주소는 다음과 같아서는 안 됩니다. https://mysite.com/getPosts 혹은 https://mysite.com/createPost 대신에 이런 모습이면 더 좋겠지요: https://mysite.com/posts

요약하자면, HTTP 메소드로 엔드포인트가 무슨 일을 할지 정하도록 하세요. GET은 데이터를 얻어오고, POST는 데이터를 생성하며, PUT은 데이터를 갱신하고, DELETE는 그 데이터를 삭제하도록 합시다.

3. 복수 명사를 사용하세요

API 데이터는 사용자로부터 얻어온 리소스라고도 볼 수 있습니다.

https://mysite.com/post/123와 같은 엔드포인트가 있다면, POST 요청으로 게시물을 지우거나, PUT 혹은 PATCH 요청을 통해 갱신하는 게 가능할 겁니다. 그러나 사용자는 다른 게시물들이 있음을 알아채기 힘들 수 있기 때문에 복수 명사를 사용해야 합니다.

따라서 https://mysite.com/post/123 보다는, https://mysite.com/posts/123이 되어야 합니다.

4. 에러 핸들링을 위해 상태 코드를 사용하세요

API 요청에 대해 응답할 때는 항상 HTTP 상태 코드를 포함해야 합니다. 그래야만 사용자가 요청이 성공했는지, 실패했는지 등 어떻게 돌아가는지 알 수 있습니다.

다음은 HTTP 상태 코드들과 의미를 담은 표입니다.

5. 관계를 보여주기 위해 엔드포인트를 중첩해 사용하세요

종종 다른 엔드포인트들은 연결되곤 합니다. 따라서 이해하기 쉽도록 중첩해 사용하세요

멀티 유저 블로그 플랫폼의 경우를 예로 들자면, 여러 게시물이 각기 다른 사용자들에 의해 작성됩니다. 따라서 엔드포인트를 https://mysite.com/posts/author 만들면 됩니다.

같은 식으로, 게시물들은 각자의 댓글들을 가지고 있기 때문에 댓글을 받아오는 엔드포인트는 https://mysite.com/posts/postId/comments 정도면 될 것 같습니다.

그렇다고 3단계 이상을 중첩하면 가독성이 떨어지기 때문에 너무 많이 중첩하지 않는 것이 좋습니다.

6. 데이터를 받을 때 필터링, 정렬, 페이지를 나누세요

API의 데이터베이스가 엄청나게 클 때가 있습니다. 그럴 때는 데이터베이스에서 데이터를 받아올 때 느려질 수가 있습니다.

필터링, 정렬, 페이지 나누기를 통해 필요한 데이터만 걸러내어 요청에 대한 부담을 줄일 수 있습니다.

필터링된 엔드포인트를 예시로 들자면 다음과 같습니다. https://mysite.com/posts?tags=javascript 이 엔드포인트는 JavaScript 태그를 가진 게시물들을 받아옵니다.

7. 보안을 위해 SSL을 적용하세요

SSL은 전송 계층 보안(Secure Socket Layer)을 나타내며, REST API 설계의 취약점을 줄이고 의심스러운 공격을 예방하는 보안에서 중요한 요소입니다.

서버와 클라이언트 사이를 비공개하고 요청한 것만큼의 데이터만 보내주는 것도 고려해야 합니다.

SSL 인증서는 등록하기 어렵지 않고, 대부분 첫 일 년은 무료입니다. 유료인 경우에도 비싼 편은 아닙니다.

REST API에서 SSL을 적용한 것과 적용하지 않은 URL에서 차이는 HTTP에 "s"의 유무입니다. https://mysite.com/posts는 SSL을 적용한 것이고, http://mysite.com/posts는 SSL을 적용하지 않은 것입니다.

8. 버전을 명시하세요

REST API는 여러 버전을 지원해서 사용자들이 최신 버전이 아니더라도 사용할 수 있게 해야 합니다. 최신 버전만 지원하게 되면, 부주의하게 버전을 올릴 시 애플리케이션에 영향을 미칠 수 있습니다.

웹 개발에서 가장 흔한 버전 관리 방법은 Semantic Versioning입니다.

Semantic versioning의 한 예는 1.0.0, 2.1.2, 3.3.4 등이 있습니다. 첫 번째 숫자는 주 버전을 의미하며, 두 번째 숫자는 부 버전을 의미하고, 세 번째 숫자는 패치 버전을 의미합니다.

큰 기업부터 개인 서비스까지 RESTful API들은 다음과 같이 제공됩니다. 버전 1 : https://mysite.com/v1/ 버전 2 : https://mysite.com/v2/

페이스북은 자사 API를 다음과 같이 버전 관리합니다.

스포티파이는 다음과 같이 제공합니다.

버전 관리에 있어 모든 API들이 위와 같이 하는 건 아닙니다. 메일침프는 좀 다르게 표기합니다.

이런 방식으로 REST API를 설계하면 사용자들이 자신의 선택에 따라 버전을 사용할 수 있습니다.

9. 정확한 API 문서를 제공하세요

REST API를 제작할 때, 사용자들이 쉽게 배울 수 있고 정확하게 사용할 수 있게 해야 합니다. 가장 좋은 방법은 API에 대한 좋은 문서를 제공하는 것입니다.

문서는 다음 내용들을 포함해야 합니다.

• 해당 API에 대한 엔드포인트
• 해당 엔드포인트에 대한 요청 예시
• 다양한 언어 지원
• 각 상태 코드에 대한 다른 에러 메시지 리스트

가장 흔히 사용하는 API 문서 툴은 Swagger입니다. API 테스트의 경우 Postman을 자주 사용합니다.

결론

이 문서에서 독자는 REST API를 설계할 때 명심해야 할 모범 사례들을 배웠습니다.

이 모범 사례들과 규칙들을 잘 실천해야 잘 작동하고 안전하며 API 사용자들이 손쉽게 사용할 수 있는 애플리케이션을 구축할 수 있습니다.

읽어주셔서 감사하며 앞으로는 API들을 해당 모범사례들을 적용해 만들어주시기를 바랍니다.