{ freetool24 }
Developer Tools

API 테스팅 가이드: 기초부터 자동화 워크플로우까지

REST API를 효과적으로 테스트하는 방법을 알아보세요 — HTTP 클라이언트를 이용한 수동 테스팅부터 자동화 테스트 스위트, 상태 코드, 인증 전략까지 다룹니다.

8분 읽기

개발자가 화면에서 API 문서를 검토하는 모습

API는 소프트웨어 시스템 간의 계약입니다. API가 중단되면, 그것에 의존하는 모든 것이 함께 중단됩니다. 그럼에도 API 테스팅은 흔히 후순위로 밀리곤 합니다 — 배포 직전에 브라우저 탭에서 수동으로 확인하는 정도로 처리되는 경우가 많죠. 체계적인 API 테스팅 전략은 버그를 조기에 발견하고, 예상 동작을 문서화하며, 자신 있게 배포할 수 있는 기반을 만들어 줍니다.

API 테스트란 무엇인가?

API 테스트는 HTTP 요청을 보내고 응답에 대해 특정 조건을 검증하는 과정입니다:

  • 상태 코드 — 200 OK를 받았는가, 아니면 404 Not Found를 받았는가?
  • 응답 본문 — 데이터 구조가 올바른가? 값이 맞는가?
  • 헤더 — Content-Type이 올바르게 설정되어 있는가? 인증 헤더가 존재하는가?
  • 응답 시간 — 엔드포인트가 허용 가능한 시간 내에 응답하는가?
  • 오류 처리 — 잘못된 입력이 들어왔을 때 어떻게 동작하는가? 의미 있는 오류 메시지를 반환하는가?

반드시 알아야 할 HTTP 상태 코드

코드 의미 발생 상황
200 OK 성공적인 GET, PUT, PATCH
201 Created 리소스를 생성하는 POST 성공
204 No Content 성공적인 DELETE 또는 응답 본문이 없는 작업
400 Bad Request 잘못된 입력, 형식이 맞지 않는 JSON, 필수 필드 누락
401 Unauthorized 인증 토큰 누락 또는 유효하지 않음
403 Forbidden 인증은 되었으나 권한 없음
404 Not Found 리소스가 존재하지 않음
409 Conflict 중복 리소스, 버전 충돌
422 Unprocessable Entity 유효한 JSON이지만 유효성 검사 오류
429 Too Many Requests 요청 속도 제한 초과
500 Internal Server Error 서버 측 버그
503 Service Unavailable 서버 다운 또는 과부하

401은 "당신이 누구인가요?"를 의미하고 — 403은 "당신이 누구인지는 알지만, 그 작업은 허용되지 않습니다"를 의미합니다.

API Request Builder로 수동 테스팅하기

자동화하기 전에, 엔드포인트를 직접 수동으로 파악해 보세요. API Request Builder를 사용하면 다음과 같은 작업이 가능합니다:

  • HTTP 메서드 설정 (GET, POST, PUT, PATCH, DELETE)
  • 헤더 추가 (Authorization, Content-Type, 커스텀 헤더)
  • URL 인코딩 없이 쿼리 파라미터 구성
  • 신택스 하이라이팅이 적용된 JSON 요청 본문 작성
  • 헤더와 타이밍을 포함한 전체 응답 확인

새로운 API를 탐색하거나, 특정 엔드포인트를 디버깅하거나, 수정 사항을 빠르게 검증할 때 매우 유용합니다.

REST API 테스팅: 전체 CRUD 사이클

가상의 /users API를 예시로, 완전한 테스트 스위트는 다음을 포함합니다:

생성 (POST)

POST /users
Content-Type: application/json

{
  "name": "Alice Chen",
  "email": "alice@example.com",
  "role": "editor"
}

검증 항목:

  • 상태 코드 201 Created
  • 응답 본문에 생성된 사용자와 자동 생성된 id 포함
  • Location 헤더가 새 리소스를 가리킴 (예: /users/42)

조회 (GET)

GET /users/42
Authorization: Bearer <token>

검증 항목:

  • 상태 코드 200 OK
  • 본문이 생성된 사용자와 일치
  • id가 42임

수정 (PUT / PATCH)

PATCH /users/42
Content-Type: application/json

{ "role": "admin" }

검증 항목:

  • 상태 코드 200 OK
  • 응답에서 role이 "admin"으로 변경됨
  • 다른 필드는 변경되지 않음

삭제 (DELETE)

DELETE /users/42
Authorization: Bearer <token>

검증 항목:

  • 상태 코드 204 No Content
  • 이후 GET /users/42 요청 시 404 반환

네거티브 테스팅: 대부분이 건너뛰는 테스트

포지티브 테스트는 정상 경로를 검증합니다. 네거티브 테스트는 API가 잘못된 입력을 올바르게 처리하는지 검증합니다:

  • 필수 필드 누락 → 명확한 오류 메시지와 함께 400
  • 잘못된 데이터 타입 ("age": "twenty") → 400
  • 존재하지 않는 리소스 (GET /users/99999) → 404
  • 만료된 토큰 → 401
  • 다른 사용자의 데이터 접근 → 403
  • 10 MB 페이로드 전송 → 413 Payload Too Large
  • 요청 속도 제한 초과 → Retry-After 헤더와 함께 429

잘 설계된 API는 예측 가능하고 유익한 방식으로 실패합니다.

인증 테스팅 패턴

Bearer 토큰 (JWT)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

테스트 시나리오:

  • 유효한 토큰 → 올바른 응답
  • 만료된 토큰 → "Token expired" 메시지와 함께 401
  • 변조된 토큰 (한 문자 변경) → 401
  • 헤더 누락 → 401
  • 다른 환경용 토큰 → 401

수동 테스팅 중 토큰을 확인하고 만료 시간을 체크하려면 JWT Decoder를 사용하세요.

API 키

X-API-Key: sk_live_abc123

테스트 항목: 잘못된 키, 키 누락, 권한이 부족한 키.

OAuth 2.0 플로우

OAuth는 복잡성을 추가합니다 — 토큰 교환 엔드포인트와 리소스 엔드포인트를 별도로 테스트하세요.

응답 본문 유효성 검사

상태 코드만 확인하지 마세요. 응답의 구조도 검증해야 합니다:

// Using Jest + supertest
test("GET /users/:id returns the correct user", async () => {
  const response = await request(app).get("/users/42").set("Authorization", `Bearer ${token}`);

  expect(response.status).toBe(200);
  expect(response.headers["content-type"]).toMatch(/json/);
  expect(response.body).toMatchObject({
    id: 42,
    name: expect.any(String),
    email: expect.stringMatching(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
    role: expect.oneOf(["admin", "editor", "viewer"]),
  });
});

더 큰 응답 스키마의 경우, JSON Schema Validator를 사용해 JSON Schema 유효성 검사를 적용하세요. 예상 형태를 한 번 정의해 두면 모든 엔드포인트에 대해 테스트할 수 있습니다.

컨트랙트 테스팅

마이크로서비스 환경에서 컨트랙트 테스팅은 컨슈머와 프로바이더가 API 형태에 합의하고 있음을 보장합니다. 컨슈머는 필요한 것을 정의하고, 프로바이더는 그것을 충족하는지 검증합니다. Pact 같은 도구가 이를 자동화합니다.

서로 다른 팀이 각자의 서비스를 담당하는 경우 특히 유용합니다 — 필드 이름이 변경되거나 삭제되는 즉시, 통합 전에 컨트랙트 테스트가 실패합니다.

성능 및 부하 테스팅

기능 테스트는 API가 작동하는지 알려줍니다. 성능 테스트는 부하 상황에서 얼마나 잘 작동하는지 알려줍니다:

  • 기준선 측정 — 단일 사용자 기준 p50/p95/p99 응답 시간은?
  • 부하 테스트 — 예상 최대 트래픽에서 성능은 어떤가?
  • 스트레스 테스트 — 어느 시점에서 실패가 시작되는가?
  • 스파이크 테스트 — 갑작스러운 10× 트래픽 증가 시 어떻게 되는가?

일반적인 목표: 예상 최대 부하에서 p95 응답 시간 200ms 미만.

API 테스팅 체크리스트

  • 각 리소스의 모든 CRUD 작업 테스트
  • 네거티브 케이스 테스트: 잘못된 입력, 인증 누락, 리소스 없음
  • 상태 코드뿐만 아니라 스키마를 기준으로 응답 본문 유효성 검사
  • 인증 엣지 케이스 테스트: 만료, 누락, 변조된 토큰
  • 오류 응답에 유용한 메시지가 포함되어 있는지 확인
  • 페이지네이션, 필터링, 정렬이 올바르게 동작하는지 테스트
  • 요청 속도 제한 동작 테스트
  • 오류 응답에 민감한 데이터가 노출되지 않는지 확인
  • 예상 부하에서 응답 시간 확인

좋은 API 테스트는 리팩토링을 위한 안전망이자, 여러분이 만들 수 있는 최고의 문서입니다 — 각 엔드포인트가 무엇을 하고 무엇을 기대하는지 정확하게 보여주기 때문입니다.

모든 아티클로 돌아가기도구 둘러보기