토스페이먼츠 Open API, 수십 년을 위한 안정적인 설계

1. 일관성 있고 예측 가능한 인터페이스 설계

리소스 중심 설계를 통해 API 경로(Path)는 root/version/domain/{id} 형태로, 요청과 응답은 JSON 객체 재사용으로 일관된 구조를 제공합니다.
데이터 표현은 한글 또는 영어로 직관성을 높이며, HTTP Accept-Language 헤더로 다국어를 지원합니다.
오류 발생 시 HTTP 상태 코드와 더불어 표준화된 오류 객체(code, message)를 제공하여 유연한 에러 처리가 가능합니다.
**웹훅(Webhook)**은 비동기 처리에 활용되며, 이벤트 타입별로 기능을 구분하고 API와 동일한 리소스 객체 페이로드를 재사용합니다.
웹훅 전송 실패 시 Exponential Backoff 전략으로 안정적인 재전송을 보장하고, 개발자센터에서 수동 재전송 기능을 제공합니다.

OpenAPI Specification(OAS) 기반의 문서 자동화 시스템으로 연동 문서를 항상 최신 API 스펙과 동기화합니다.
샌드박스는 브라우저에서 코드를 직접 수정하고 실행하며 API를 학습할 수 있는 '보면서, 수정하면서, 실행할 수 있는' 개발 도구를 제공합니다.
테스트 환경은 실제 운영 환경과 동일한 코드 베이스를 사용하되 외부 원천사 호출을 Mock 처리하여 금전 발생 없이 안전한 검증이 가능합니다.
TossPayments-Test-Code 헤더를 통해 에러 재현 기능을 제공, 특정 오류 상황을 손쉽게 테스트하고 예외 처리를 검증합니다.
개발자센터의 API 로그 조회 기능으로 요청/응답 상세 및 오류 원인, 해결 방법을 제공하여 스스로 트러블슈팅할 수 있도록 돕습니다.
API 버저닝을 적용하여 기존 연동에 영향 없이 새로운 기능을 추가하고 스펙을 변경할 수 있으며, 릴리즈 노트로 변경 사항을 명확히 안내합니다.

API 요청 시 API Key를 통한 인증, 웹훅 수신 시 Webhook-Signature를 통한 서명 검증으로 요청 주체를 식별하고 데이터 변조를 방지합니다.
TLSv1.2 및 TLSv1.3을 전사 모든 네트워크 엔드포인트에 적용하여 안전한 통신 채널을 구축합니다.
Encryption Mode를 통해 애플리케이션 레이어에서 요청/응답 데이터를 JWT 기반 JWE로 암호화하고, iat 및 nonce로 재전송 공격을 방지합니다.
Rate Limiting 정책을 운영하여 악의적인 API 남용을 차단하고, 시스템 자원 보호 및 사고 규모 최소화에 기여합니다.

공통 라이브러리 형태로 인증, 암호화, 에러 응답, 문서 자동화 등 Open API 관련 공통 로직을 제공하여 모든 도메인의 API 일관성을 유지합니다.
Open API Committee를 통해 새로운 API의 설계 표준, 보안 정책, 품질 기준을 검토하고, 조직 전반의 API 품질 관리 및 개선을 이끌어갑니다.