개발 문서에서 URL과 JSON이 읽히지 않을 때 먼저 확인할 것

API 문서, 로그, 이슈 댓글에는 URL과 JSON이 자주 등장합니다. 한글·공백이 포함된 URL은 전달 과정에서 깨져 보일 수 있고, 한 줄로 길게 이어진 JSON은 필요한 값을 찾기 어렵습니다. 이때 내용을 추측해서 고치기보다, 표현 형식과 데이터 구조를 나눠 확인하는 편이 좋습니다.

이 글은 API 요청을 대신 보내거나 JSON의 의미를 검증하지 않습니다. 토큰, 비밀번호, 인증 코드, 고객 정보가 든 로그는 어떤 온라인 도구에도 넣지 않는 것이 원칙입니다.

URL: 인코딩과 디코딩을 구분합니다

URL 인코딩은 공백, 한글, 특수문자를 주소에서 안전하게 전달할 수 있는 문자 조합으로 바꾸는 작업입니다. 이미 인코딩된 문자열을 다시 인코딩하면 %25처럼 읽기 어려운 값이 늘어날 수 있습니다.

확인 순서는 간단합니다.

1. 원문에 %와 영문·숫자 조합이 많다면 먼저 디코딩 결과를 봅니다.
2. 사람이 읽는 한글 문장이나 공백이 들어 있다면 인코딩 결과를 만듭니다.
3. 변환 전후 중 어느 값이 요청 주소의 일부인지 API 문서와 대조합니다.

변환 결과가 나온다고 해서 그 URL이 실제로 열리거나 권한이 있다는 뜻은 아닙니다. 네트워크 요청과 접근 권한은 별도로 확인해야 합니다.

JSON: 보기 좋게 만든 뒤 구조를 읽습니다

한 줄 JSON을 줄 바꿈과 들여쓰기로 정리하면 중괄호·대괄호의 범위를 훨씬 빠르게 확인할 수 있습니다. 예를 들어 응답의 data 안에 배열이 있는지, 오류 코드가 최상위에 있는지처럼 구조를 먼저 파악할 수 있습니다.

다만 JSON 정리는 문법이 올바를 때만 가능합니다. 따옴표나 쉼표가 빠진 문자열은 결과 대신 오류 안내가 나와야 합니다. 이 경우에는 일부를 임의로 삭제하기보다, 원본 로그와 생성 코드를 다시 대조하는 편이 낫습니다.

URL 인코딩·디코딩과 JSON 정리를 한 화면에서 확인하려면 바로정리의 형식 변환 도구를 사용할 수 있습니다.

도구: https://barojungri-tools-yh.yonggoo0001.chatgpt.site/

입력하면 안 되는 값

형식만 확인하는 작업이라도 다음 값은 입력하지 마세요.

- API 키와 접근 토큰
- 비밀번호, 인증번호, 세션 값
- 고객 이름·연락처·주소가 포함된 응답
- 결제 정보 또는 사내 비공개 로그

안전한 예제 값으로 형식을 재현하거나, 민감한 부분을 REDACTED처럼 바꾼 뒤 확인하는 방식이 좋습니다.

정리

URL은 ‘문자 표현’을, JSON은 ‘데이터 구조’를 먼저 확인해야 합니다. 작은 형식 정리는 디버깅의 출발점이 될 수 있지만, 요청의 성공 여부·권한·데이터 의미까지 대신 판단해 주지는 않습니다.

추천 태그: JSON, URL인코딩, API문서, 개발팁, 데이터형식