API 개발 필수 도구: 더 빠른 디버깅, 더 빠른 배포

오후 3시인데 API가 401을 리턴하고 있어. 토큰은 유효해 보여. 엔드포인트는 맞아. 요청 헤더도 괜찮아 보여.

JWT를 디코더에 붙여넣으니 문제가 바로 보여: exp 클레임이 12분 전에 만료됐어. 토큰 갱신 로직에 버그가 있는 거야.

5초짜리 디코딩이 코드만 쳐다보며 보냈을 한 시간을 절약해줬어.

JWT 디버깅은 매일의 작업

모던 API를 다루면 JWT를 끊임없이 다뤄. 로그인 토큰, 서비스 간 인증, OAuth 플로우 — 어디에나 있어.

문제는 JWT가 의미 없는 문자열처럼 보인다는 거야:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

어떤 클레임이 있어? 언제 만료돼? 어떤 알고리즘으로 서명됐어? 봐서는 알 수 없어.

토큰을 붙여넣으면 헤더, 페이로드, 만료를 즉시 확인할 수 있어. 라이브러리를 설치할 필요 없어. 코드를 쓸 필요 없어. 그냥 답만.

HTTP 상태 코드: 200과 404 너머

빨리 — 401이랑 403의 차이가 뭐야? 502랑 503은? 409를 써야 할 때와 422를 써야 할 때는?

대부분의 개발자가 흔한 것들은 알지만, API는 수십 가지 다른 상태 코드를 리턴해. 예상치 못한 429나 혼란스러운 307을 받으면 정확히 무슨 뜻인지 알아야 해.

HTTP 상태 코드 레퍼런스가 각 코드의 의미, 사용 시점, 흔한 원인을 알려줘. 구글링보다 빠르고 Stack Overflow 토론을 뒤질 필요 없어.

JSON 포맷팅은 선택이 아니야

API는 JSON을 보내고 받아. 그리고 대부분의 경우 그 JSON은 공백 없이 한 줄로 압축되어 도착해.

{"users":[{"id":1,"name":"Alice","roles":["admin","editor"],"settings":{"theme":"dark","notifications":{"email":true,"push":false}}}]}

여기서 빠진 쉼표를 찾아봐. 또는 중첩된 필드가 있는지 확인해봐. 또는 두 응답을 비교해봐.

압축된 JSON을 붙여넣으면 적절한 들여쓰기로 포맷팅 돼. 이제 실제로 읽을 수 있고, 오류를 찾고, 구조를 비교할 수 있어.

Base64: 인증 헤더의 비밀

API 인증은 종종 Base64 인코딩을 포함해. Basic Auth 헤더는 username:password를 Base64로 인코딩한 거야. JSON 페이로드의 바이너리 데이터도 Base64로 인코딩돼. 인증서 내용, 웹훅 서명, 암호화된 값 — 전부 Base64야.

뭔가 작동하지 않을 때 실제로 뭐가 전송되고 있는지 디코딩해야 해. 또는 테스트할 새로운 값을 인코딩해야 해.

Base64 인코더/디코더가 양방향으로 즉시 처리해. 인코딩된 문자열을 붙여넣으면 원래 값이 보여. 새 값을 입력하면 인코딩된 버전을 받아.

흔한 디버깅 시나리오: Basic Auth 헤더가 실패해. 디코딩해보니 비밀번호에 줄바꿈 문자가 붙어있었어. 코드에서 발견하려면 훨씬 오래 걸렸을 거야.

URL 인코딩은 까다로워져

특수 문자가 있는 쿼리 파라미터는 URL 인코딩이 필요해. 공백은 %20(또는 +)이 되고, 앰퍼샌드는 %26이 되고, 슬래시는 %2F가 돼.

이게 중요한 경우:

• 사용자 입력이 있는 검색 엔드포인트를 만들 때
• 쿼리 파라미터에 URL이 포함될 때 (콜백 URL, 리다이렉트 URI)
• 파라미터가 왜 제대로 파싱 안 되는지 디버깅할 때
• API 키에 특수 문자가 있을 때

URL 인코더/디코더가 인코딩/디코딩된 버전이 정확히 어떻게 보이는지 보여줘. 특히 URL 안에 URL이 들어가서 이중 인코딩되면 읽을 수 없게 되는 OAuth 콜백 URL 디버깅할 때 유용해.

실제 디버깅 워크플로우

이 도구들이 실제 API 디버깅 세션에서 어떻게 쓰이는지:

1. 요청 실패 — HTTP 상태 코드 의미 확인
2. 인증 이슈? — JWT를 디코딩해서 클레임과 만료 확인
3. 페이로드 문제? — JSON을 포맷팅해서 구조 검사
4. 헤더 이슈? — Base64 인증 헤더 디코딩
5. URL 파싱? — URL을 디코딩해서 파라미터 인코딩 확인

각 단계가 몇 초 걸려. 대안 — 일회용 스크립트 작성, CLI 도구 설치, 문서 뒤지기 — 은 몇 분에서 몇 시간이 걸려.

항상 열어두기

이 도구들을 브라우저 고정 탭에 두고 있어. Base64 인코딩을 파이썬으로 못 해서가 아니야. 할 수 있어. 하지만 터미널로 컨텍스트 스위칭하고 빠른 스크립트를 작성하고 실행하는 건 디버깅 흐름을 끊어.

이 도구들은 디버깅 속도야. 붙여넣고, 결과 보고, 문제 이해하고, 코드 수정. 가능한 가장 빠른 디버깅 사이클.

---

API 개발은 50%가 코드를 쓰는 것이고 50%가 왜 내가 쓴 코드가 기대대로 작동하지 않는지 알아내는 거야. 적절한 브라우저 도구는 IDE나 디버거를 대체하지 않아 — "알아내기" 부분을 더 빠르게 만들어서 보완해줘.