API 응답을 안전하게 수정하는 체크리스트

API 응답을 수정할 때 로컬에서 괜찮았던 코드도 배포 환경에서는 다르게 동작할 수 있다. 특히 JSON 응답의 필드를 추가하거나 제거할 때는 더욱 주의해야 한다.

status code부터 확인하기

API 문제를 마주칠 때는 화면만 보고 판단하면 놓치는 값이 많다. 먼저 실제 요청이 어떻게 이루어지는지 확인해야 한다.

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

이 명령으로 status code, 응답 헤더, 응답 body를 한 번에 볼 수 있다. 에러 메시지부터 확인하면 불필요한 변경을 많이 줄일 수 있다.

요청과 응답의 흐름 추적하기

API 응답이 애매해 보일 때는 요청부터 응답까지 전체 흐름을 끊어서 본다. 에러 상황을 재현할 수 있어야 원인을 좁힐 수 있기 때문이다.

• 먼저 볼 것: status code와 에러 메시지
• 같이 비교할 것: 정상일 때의 응답 형식
• 기록해둘 것: 성공/실패한 요청의 파라미터와 응답

단계적으로 검증하기

응답 구조를 바꿀 때는 한 번에 여러 필드를 수정하지 않는 게 중요하다.

1. 현재 응답이 실제로 어떤 형태인지 재현해본다
2. 로그나 응답에서 바뀐 부분을 정확히 파악한다
3. 실제 클라이언트에서 새 응답을 제대로 받는지 확인한다

다음을 위해 남겨두기

해결 자체보다 어떤 값이 달라졌는지 설명할 수 있는 상태가 더 중요하다. 요청 파라미터와 응답을 기록해두면 다음 수정이 훨씬 빨라진다.