API 응답 형식이 바뀔 때 안전하게 대응하기

API를 운영하다 보면 응답 형식을 바꿔야 할 때가 온다. 새로운 필드를 추가하거나, 불필요한 필드를 제거하거나, 자료 구조를 재구성할 때다. 이 작업에서 실수하면 클라이언트 앱들이 깨진다.

현재 사용 중인 필드부터 파악하자

API 응답에는 여러 필드가 있는데, 실제로 어느 필드를 사용하는지 파악해야 한다. 로그나 모니터링 데이터를 보면, 자주 요청되는 엔드포인트와 주요 필드를 알 수 있다.

한 번에 여러 필드를 바꾸려고 하면 어느 변경이 문제를 일으켰는지 알 수 없으니, 한 가지씩 진행하자.

응답을 직접 확인해보자

실제 사용 중인 API를 호출해서 응답을 본다.

curl -i 'https://example.com/api/items?page=1'

응답 상태 코드, 응답 헤더, 응답 body를 모두 확인한다. 특히 Content-Type, Cache-Control 같은 헤더도 중요하다.

필드 추가는 하위 호환성을 유지하자

새로운 필드를 추가할 때는 기존 클라이언트가 그 필드를 무시할 수 있도록 해야 한다. 즉, optional 필드로 추가하거나, 기본값을 명확히 해야 한다.

기존 클라이언트는 새로운 필드를 받으면 무시하고, 새로운 클라이언트만 그 필드를 사용하도록 구분해야 한다.

필드 제거는 점진적으로

불필요한 필드를 제거하려면 한 번에 없애지 말고, 여러 버전에 걸쳐서 진행하자.

1. 첫 번째: 필드를 deprecated 표시하고 로그를 남긴다.
2. 두 번째: deprecated 필드를 여전히 보내지만, 클라이언트에 경고를 준다.
3. 세 번째: 필드를 제거하고 새 버전으로 올린다.

이렇게 하면 클라이언트들이 단계적으로 대응할 수 있다.

인증 상태에 따른 응답 차이

API 응답은 로그인 상태나 권한에 따라 달라질 수 있다. 테스트할 때는 다양한 상황을 고려해야 한다:

• 인증 없이 호출
• 일반 사용자 권한으로 호출
• 관리자 권한으로 호출

각 상황에서 응답이 기대하는 대로 나오는지 확인하자.

백업하고 롤백 계획을 준비하자

API 변경을 배포하기 전에 현재 응답을 저장해두고, 문제가 생기면 빠르게 이전 버전으로 돌아갈 수 있도록 준비한다.

배포 후 모니터링을 강화해서, 클라이언트 에러율이 갑자기 올라가지 않는지 확인하자.