API v1에서 v2로 마이그레이션

개요

API v2는 캡처 세션(Capture Session) 개념을 도입하여 지문과 외관 이미지를 처리하는 방식을 개선했습니다. 이 가이드는 v1에서 v2로의 마이그레이션 방법을 안내합니다.

주요 변경사항

캡처 세션 도입

v1에서는 파일 업로드 시 메타데이터(species, purpose)를 함께 전달했지만, v2에서는 캡처 세션을 먼저 생성하고 해당 세션 내에서 파일을 업로드합니다.

항목	API v1	API v2
메타데이터 전달	매 업로드마다 전달	세션 생성 시 1회만 전달
파일 그룹핑	수동으로 ID 관리	세션으로 자동 그룹핑
작업 요청	파일 ID 목록 전달	세션 ID만 전달

엔드포인트 변경

기능	v1 엔드포인트	v2 엔드포인트
지문 업로드	`POST /v1/fingerprints:upload`	`POST /v2/fingerprints:upload`
외관 업로드	`POST /v1/appearances:upload`	`POST /v2/appearances:upload`
펫 검증	`POST /v1/pets/{petId}:verify`	`POST /v2/pets/{petId}:verify`
펫 식별	`POST /v1/pets:identify`	`POST /v2/pets:identify`
지문 추가	`POST /v1/pets/{petId}:addFingerprints`	`POST /v2/pets/{petId}:addFingerprints`
신규	-	`POST /v2/capture-sessions`

워크플로우 비교

v1 워크플로우

v2 워크플로우

세션 자동 연결: 업로드 시 sessionId 쿼리 파라미터를 사용하면 파일이 자동으로 해당 세션에 연결됩니다. 별도의 세션 종료 API 호출은 필요하지 않으며, action(verify, identify, addFingerprints) 수행 시 세션의 모든 파일이 자동으로 사용됩니다.

코드 마이그레이션 예시

v1 코드 (이전)

// v1: 파일 업로드 시마다 메타데이터 전달
const fp1 = await fetch('/v1/fingerprints:upload', {
  method: 'POST',
  body: createFormData({
    file: file1,
    species: 'DOG',
    purpose: 'PET_VERIFICATION'
  })
}).then(r => r.json());

const fp2 = await fetch('/v1/fingerprints:upload', {
  method: 'POST',
  body: createFormData({
    file: file2,
    species: 'DOG',
    purpose: 'PET_VERIFICATION'
  })
}).then(r => r.json());

// v1: 파일 ID 목록으로 직접 검증
const verifyResult = await fetch(`/v1/pets/${petId}:verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    fingerprints: [fp1.data.id, fp2.data.id]
  })
}).then(r => r.json());

v2 코드 (이후)

// v2: 세션 생성 (메타데이터는 1회만)
const session = await fetch('/v2/capture-sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    species: 'DOG',
    purpose: 'PET_VERIFICATION',
    petId: petId
  })
}).then(r => r.json());

// v2: 파일 업로드 (sessionId 쿼리 파라미터로 자동 연결)
const fp1 = await fetch(`/v2/fingerprints:upload?sessionId=${session.data.sessionId}`, {
  method: 'POST',
  body: createFormData({ file: file1 })
}).then(r => r.json());

const fp2 = await fetch(`/v2/fingerprints:upload?sessionId=${session.data.sessionId}`, {
  method: 'POST',
  body: createFormData({ file: file2 })
}).then(r => r.json());

// v2: 세션 ID로 검증 (업로드된 모든 파일 자동 사용)
const verifyResult = await fetch(`/v2/pets/${petId}:verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sessionId: session.data.sessionId
  })
}).then(r => r.json());

세션 상태

캡처 세션은 다음 상태를 가집니다:

상태	설명
`STARTED`	세션이 활성화되어 업로드를 받을 준비가 됨
`FINISHED`	캡처된 데이터로 세션이 성공적으로 종료됨
`ABORTED`	세션이 취소되거나 실패함
`TIMEOUT`	세션이 정상적으로 종료되지 않고 만료됨

업로드 요구사항

작업	최소 지문 개수
등록 (Registration)	5장
검증 (Verification)	3장
식별 (Identification)	3장

마이그레이션 체크리스트

세션 생성 로직 추가 (POST /v2/capture-sessions)
파일 업로드 URL에 sessionId 쿼리 파라미터 추가
파일 업로드 요청 본문에서 species, purpose 메타데이터 제거
검증/식별 요청에서 파일 ID 목록 대신 세션 ID 사용
세션 종료 로직 제거 (자동 처리됨)
에러 핸들링에 세션 관련 에러 추가
엔드포인트 URL 경로 /v1/ → /v2/ 변경

v2의 장점

메타데이터 관리 간소화: 종(species)과 목적(purpose)을 세션 생성 시 한 번만 설정
추적 개선: 한 작업의 모든 업로드가 세션으로 자동 그룹핑
검증 강화: 처리 전에 최소 요구사항 자동 확인
확장성: 세션 기반 아키텍처로 진행 상황 추적, 재개 가능한 업로드 등 향후 기능 지원

일반적인 마이그레이션 오류

세션 없이 업로드 시도

{
  "error": "세션 컨텍스트가 필요합니다"
}

해결책: 파일 업로드 전에 캡처 세션을 생성하세요.

sessionId 쿼리 파라미터 누락

{
  "error": "세션 ID가 필요합니다"
}

해결책: 업로드 URL에 ?sessionId={sessionId} 쿼리 파라미터를 추가하세요.

검증에 펫 ID 누락

{
  "error": "검증 목적으로는 펫 ID가 필요합니다"
}

해결책: 캡처 세션 생성 시 petId를 포함하세요.