REST API 9회차 : 버전 관리·문서화·테스트까지 한 번에 정리

/v1 버전 관리, OpenAPI(Swagger) 문서, Postman·Insomnia·pytest로 테스트하는 과정을 한 장에 담은 개념 이미지입니다.

REST API 9회차 : 버전 관리·문서화·테스트까지 한 번에 정리

한눈에 보는 요약

이번 글에서는 실무 REST API에서 반드시 다루어야 하는 세 가지 축, 즉 /v1 버전 전략, OpenAPI(Swagger) 기반 자동 문서화, Postman·Insomnia·pytest를 활용한 테스트를 하나의 흐름으로 정리합니다.

/v1 같이 URL에 버전을 넣는 방식이 왜 많이 쓰이는지, 어떤 기준으로 v2를 만들고 구버전을 유지할지 등 버전 정책의 기본 원칙을 설명합니다.

또한 OpenAPI 스펙을 사용해 API 문서를 자동으로 생성하고, 이 문서를 Postman·Insomnia 같은 도구에서 그대로 가져와 테스트에 활용하는 방법을 소개합니다.

마지막으로 간단한 OpenAPI 예시를 읽고, 요약·파라미터·응답 스키마를 직접 수정해보는 실습 아이디어까지 제시합니다.

목차

• 1. 핵심 포인트
• 2. /v1 스타일 API 버전 전략
• 3. OpenAPI(Swagger)로 문서 자동화
• 4. Postman·Insomnia·pytest로 API 테스트하기
• 5. 실습: OpenAPI 예시 읽고 직접 수정해 보기
• 6. 코드 예시
• 7. 실행 단계 정리
• 8. 추가로 생각해볼 점
• 9. 블로그 최적화 정보

---

핵심 포인트

• /v1 버전 전략의 핵심은 “호환성 유지”와 “변경 관리”입니다. URL에 버전을 명시하면 클라이언트가 어느 버전을 사용하는지 명확해지고, 서버는 v1·v2를 동시에 운영하며 점진적으로 이전할 수 있습니다.
• OpenAPI(Swagger)는 API를 YAML/JSON으로 구조화해 정의하는 표준입니다. 한 번 정의하면 사람용 문서, SDK, 테스트 스크립트까지 자동으로 생성하는, 말 그대로 “단일 소스 오브 트루스(single source of truth)” 역할을 합니다.
• Postman·Insomnia는 수동 테스트와 스크립트 기반 자동화 테스트를 동시에 지원하는 도구로, OpenAPI 스펙을 가져와 컬렉션을 자동 생성하는 기능을 제공합니다.
• pytest와 같은 테스트 프레임워크를 사용하면, API 호출을 코드로 관리하면서 회귀 테스트를 자동화해 배포 시 안정성을 크게 높일 수 있습니다.
• 실습에서는 간단한 OpenAPI 스펙을 읽고, 요약(summary)와 설명(description)을 바꾸고, 쿼리 파라미터와 응답 예시를 추가하며 구조를 몸으로 익혀 봅니다.

상세 설명

1. /v1 스타일 API 버전 전략

REST API에서 버전 관리는 “한 번 배포된 API는 쉽게 깨뜨리지 않는다”는 원칙에서 시작합니다. 프론트엔드·모바일 앱·외부 파트너 등 다양한 클라이언트가 API를 사용하기 때문에, 기존 클라이언트가 갑자기 동작하지 않는 상황은 반드시 피해야 합니다.

가장 널리 쓰이는 방법이 /v1 같이 URL 경로에 버전을 명시하는 방식입니다. 예를 들어 사용자 조회 엔드포인트가 있다면 다음과 같이 정의합니다.

• GET /api/v1/users – 1버전 사용자 목록 조회
• GET /api/v2/users – 2버전 사용자 목록 조회(예: 필드 구조가 바뀐 경우)

이 방식의 장점은 클라이언트와 서버 모두 버전을 한눈에 파악할 수 있다는 점입니다. 또한 v1, v2를 동시에 운영하면서, 일정 기간 동안은 v1을 유지하고 공지 후 단계적으로 종료할 수 있습니다.

2. 언제 v2를 만들 것인가?

버전을 올리는 기준은 “기존 클라이언트가 깨지는지 여부”로 판단하는 것이 좋습니다.

• 버전을 올리지 않아도 되는 변경
  • 본문에 새로운 필드를 추가하지만, 기존 필드는 그대로 두는 경우
  • 내부 구현 변경(쿼리 최적화, 캐시 적용 등)으로 응답 구조는 그대로인 경우
  • 기본값이 안전하게 설정된 선택적 파라미터(optional parameter)를 추가하는 경우
• 새 버전(v2 등)을 고려해야 하는 변경
  • 필드 이름을 변경하거나 필드를 제거해서 기존 파싱 로직이 깨지는 경우
  • URL 경로 구조를 대폭 개편하는 경우 (예: /users/{id} → /members/{id})
  • 응답 포맷을 JSON → XML 같이 전혀 다른 형식으로 바꾸는 경우

이처럼 “하위 호환성(backward compatibility)”이 깨지는 변경은 /v2와 같은 새로운 버전에서 처리하고, 구버전은 일정 기간 유지하면서 마이그레이션 가이드를 제공하는 것이 일반적입니다.

3. 버전 관리 방식 비교

URL 버전 외에도 HTTP 헤더나 쿼리 파라미터로 버전을 관리하는 방식이 존재합니다. 아래 표는 대표적인 세 가지 방식을 비교한 것입니다.

방식	예시	장점	단점	실무 사용 빈도
URL 경로 버전	/api/v1/users	가독성이 높고 라우팅 설정이 단순하다.	URL이 바뀌므로 링크 공유 시 버전 업그레이드가 번거로울 수 있다.	가장 많이 사용됨
HTTP 헤더 버전	Accept: application/vnd.myapp.v1+json	URL을 깔끔하게 유지할 수 있다.	클라이언트 설정이 다소 복잡하며, 브라우저 테스트가 불편할 수 있다.	대형 API에서 일부 사용
쿼리 파라미터	/api/users?version=1	기존 URL 구조를 크게 바꾸지 않고 도입할 수 있다.	버전이 필수 정보임에도 선택적 파라미터처럼 보인다.	권장도는 낮음

4. OpenAPI(Swagger)로 문서 자동화

OpenAPI는 REST API의 엔드포인트, 파라미터, 응답 형식 등을 표준화된 형식(YAML/JSON)으로 정의하는 스펙입니다. 예전에는 “Swagger 스펙”이라고 불렸지만, 현재는 스펙 이름이 OpenAPI이고 Swagger는 이를 구현한 도구들의 브랜드라고 이해하시면 됩니다.

OpenAPI의 가장 큰 장점은 “한 번 정의하면 여러 출력을 얻을 수 있다”는 점입니다.

• Swagger UI, ReDoc 등 사람 눈에 보기 좋은 웹 문서 자동 생성
• Postman·Insomnia 컬렉션, 클라이언트 SDK(Java, TypeScript 등) 자동 생성
• API 서버 스텁 코드(Controller 인터페이스 등) 자동 생성

즉, OpenAPI 문서를 잘 관리하면, 엑셀·위키·구글 문서 등 여러 곳에서 API를 따로따로 설명할 필요 없이 한 곳에서 전체를 관리할 수 있습니다.

5. OpenAPI 문서의 기본 구조

OpenAPI 3.x 기준으로, 문서의 큰 틀은 다음과 같이 구성됩니다.

• openapi: 스펙 버전 (예: 3.0.3)
• info: 제목, 설명, 버전 등 메타데이터
• servers: 실제 API 서버 URL 목록
• paths: 각 엔드포인트(/users, /users/{id} 등) 정의
• components: 재사용 가능한 스키마, 응답, 파라미터 정의

6. Postman·Insomnia·pytest로 API 테스트하기

문서화가 끝났다면 다음 단계는 “테스트 자동화”입니다. 구현된 API가 문서와 일치하는지, 변경 후에도 기존 기능이 깨지지 않는지 검증해야 합니다.

• Postman: GUI 기반으로 요청을 만들고, 컬렉션 단위로 테스트 스크립트를 작성할 수 있습니다. OpenAPI 파일을 임포트하면 엔드포인트가 자동으로 생성되어 빠르게 테스트를 시작할 수 있습니다.
• Insomnia: 비슷한 용도의 도구로, 환경 변수·템플릿 기능이 강점입니다. 팀 협업과 Git 저장소 연동이 용이합니다.
• pytest: Python 기반의 테스트 프레임워크로, requests 라이브러리와 함께 사용하면 API 테스트를 코드로 관리할 수 있습니다.

수동 테스트(Postman·Insomnia)와 자동 테스트(pytest)는 상호 보완적입니다. 개발 초기에는 수동으로 빠르게 시도해 보고, 시나리오가 굳어지면 pytest로 옮겨 회귀 테스트를 자동화하는 패턴이 많이 사용됩니다.

7. 실습: OpenAPI 예시 읽고 수정하기

이제 이론을 실제 문서에 적용해 보는 간단한 실습을 제안드립니다. 아래와 같은 순서로 진행해 보시면 좋습니다.

1. 간단한 OpenAPI YAML 예시를 준비합니다. (아래 코드 예시 참고)
2. info.title, info.version, paths 아래의 summary와 description을 읽고, 비즈니스 도메인에 맞게 한글로 수정합니다.
3. 사용자 목록 엔드포인트에 limit, offset 같은 쿼리 파라미터를 추가해 보고, 각 파라미터의 타입과 설명을 적습니다.
4. 응답 스키마에 email, createdAt 같은 필드를 추가하고, 예시 응답(example)을 작성합니다.
5. 수정한 YAML을 Swagger UI 또는 Postman에 임포트해 실제 화면에서 어떻게 보이는지 확인합니다.

이 과정을 거치면 “문서 작성 → 코드 수정 → 테스트”의 전체 흐름을 몸으로 익힐 수 있습니다.

코드 예시

openapi: 3.0.3
info:
  title: Sample User API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: 사용자 목록 조회
      description: 활성화된 사용자 목록을 페이지 단위로 조회합니다.
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
          description: 한 페이지에 조회할 최대 사용자 수
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

위 예시는 간단한 사용자 목록 API를 OpenAPI 3.0 형식으로 정의한 것입니다. info, servers, paths, components로 구조가 나뉘어 있고, /users GET 엔드포인트에 쿼리 파라미터와 응답 스키마가 정의되어 있습니다. 여기서 summary·description을 비즈니스 용어에 맞게 바꾸고, User 스키마에 필요한 필드를 더 추가해 보시면 좋습니다.

import requests

BASE_URL = "https://api.example.com/v1"

def test_get_users_returns_200():
    resp = requests.get(f"{BASE_URL}/users", params={"limit": 10})
    assert resp.status_code == 200
    data = resp.json()
    assert isinstance(data, list)
    assert len(data) <= 10
    if data:
        user = data[0]
        assert "id" in user
        assert "name" in user
        assert "email" in user

이 pytest 예시는 /v1/users 엔드포인트가 200 응답을 반환하고, JSON 배열 구조와 기본 필드(id, name, email)를 가진다는 것을 검증합니다. CI 파이프라인에 이 테스트를 포함하면, 코드 변경 후에도 API 계약이 깨지지 않았는지 자동으로 확인할 수 있습니다.

---

실행 단계

1. /v1 버전 규칙 정하기 – 팀 내에서 “하위 호환성을 깨는 변경”의 기준을 합의하고, 언제 v2를 만들지, 구버전을 얼마나 유지할지 정책을 문서화합니다.
2. OpenAPI 기본 스펙 작성 – 현재 운영 중인 주요 엔드포인트를 중심으로 OpenAPI YAML/JSON을 작성하고, Swagger UI 또는 관련 플러그인으로 문서를 자동 생성합니다.
3. Postman·Insomnia에 임포트 – 작성한 OpenAPI 파일을 Postman이나 Insomnia에 가져와 컬렉션을 생성하고, 환경 변수(base URL, 토큰 등)를 설정합니다.
4. 테스트 스크립트 추가 – 중요한 엔드포인트에 대해 상태 코드, 응답 시간, 필수 필드 존재 여부 등을 검증하는 테스트 스크립트를 Postman 또는 pytest에 작성합니다.
5. CI 파이프라인 연동 – 코드 저장소에 테스트 스크립트를 포함하고, Pull Request 또는 배포 전 단계에서 자동으로 실행되도록 CI 설정을 구성합니다.
6. 정기적으로 버전·문서·테스트 리뷰 – 분기별 또는 주요 릴리스마다 버전 정책과 OpenAPI 문서, 테스트 케이스를 함께 검토해 누락된 엔드포인트나 오래된 설명을 정리합니다.

추가로 생각해볼 점

• 버전 관리, 문서화, 테스트는 각각 독립된 작업이 아니라 하나의 라이프사이클입니다. 새 기능을 설계할 때부터 이 세 가지를 동시에 고려하면, 나중에 문서와 코드가 어긋나는 문제를 크게 줄일 수 있습니다.
• 내부·외부 소비자(사내 다른 팀, 파트너사, 공개 API 사용자 등)에 따라 버전 종료 정책과 공지 방식이 달라질 수 있으므로, 대상별 가이드를 미리 준비해 두시는 것이 좋습니다.
• 장기적으로는 API Gateway, Rate Limiting, Observability(로그·메트릭·트레이싱)까지 포함한 “API 플랫폼” 관점에서 버전·문서·테스트 전략을 통합적으로 설계하는 것이 이상적입니다.