REST API를 위한 URL 인코딩 모범 사례

API에서 URL 인코딩이 중요한 이유

올바른 URL 인코딩은 REST API 개발에서 매우 중요합니다. 잘못 인코딩된 URL은 요청 실패, 보안 취약점, 데이터 손실, 그리고 서로 다른 시스템과 프로그래밍 언어 간의 상호 운용성 문제로 이어질 수 있습니다. API 개발자라면 요청을 보낼 때 URL을 인코딩하는 방법과 요청을 처리할 때 이를 디코딩하는 방법을 모두 이해해야 합니다.

경로 파라미터 인코딩

REST API는 리소스를 식별하기 위해 경로 파라미터를 자주 사용합니다. 이러한 파라미터에 특수 문자가 포함되어 있을 때는 올바른 인코딩이 필수적입니다.

// 특수 문자가 포함된 경로 파라미터
// 리소스: "Tom & Jerry's Show"
GET /api/shows/Tom%20%26%20Jerry%27s%20Show

// JavaScript 사용
const showName = "Tom & Jerry's Show";
const url = `/api/shows/${encodeURIComponent(showName)}`;

// 값에 슬래시(/)가 포함된 경로
// 파일: "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

쿼리 파라미터 인코딩

쿼리 파라미터는 인코딩 문제가 가장 흔하게 발생하는 부분입니다. 키와 값을 항상 함께 인코딩하세요.

// 특수 문자가 포함된 여러 파라미터
GET /api/search?q=C%2B%2B%20programming&category=languages%20%26%20tools&page=1

// URLSearchParams 사용 (권장)
const params = new URLSearchParams({
  q: 'C++ programming',
  category: 'languages & tools',
  page: '1'
});
const url = '/api/search?' + params.toString();

쿼리 문자열에서 배열과 객체 다루기

API 프레임워크마다 배열 파라미터를 처리하는 방식이 다릅니다. 다음은 자주 사용되는 관례들입니다.

// 키 반복 (가장 일반적)
GET /api/items?tag=javascript&tag=typescript&tag=react

// 대괄호 표기법 (PHP, Rails)
GET /api/items?tags[]=javascript&tags[]=typescript

// 쉼표 구분 (일부 REST API)
GET /api/items?tags=javascript,typescript,react

// 중첩 객체 (대괄호 표기법)
GET /api/search?filter[status]=active&filter[sort]=date

Content-Type과 인코딩

Content-Type 헤더는 요청 본문(body) 데이터가 어떻게 인코딩되는지를 결정합니다.

• application/x-www-form-urlencoded - URL 쿼리 문자열과 유사합니다. 키와 값이 인코딩되며 공백은 +로 변환됩니다
• multipart/form-data - 파일 업로드에 사용됩니다. 각 파트가 자체적인 인코딩을 가집니다
• application/json - JSON 형식입니다. 본문에는 URL 인코딩이 필요 없지만, Content-Type을 올바르게 설정해야 합니다

API 보안 고려 사항

• 서버에서는 디코딩된 URL 파라미터를 항상 검증하고 정제하세요
• %2e%2e%2f(../)와 같이 인코딩된 시퀀스를 통한 경로 탐색(path traversal) 공격에 유의하세요
• 서비스 거부(DoS) 공격을 방지하기 위해 URL 길이 제한을 구현하세요
• 클라이언트 측 인코딩을 절대 신뢰하지 말고, 서버에서 항상 다시 검증하세요
• 한 번 디코딩한 후에 악성 입력이 필터를 우회하는 이중 인코딩(double-encoding) 공격을 주의하세요
• URL 디코딩 이후에도 SQL 인젝션을 방지할 수 있도록 파라미터화된 쿼리를 사용하세요

API에서 URL 인코딩 테스트하기

API 엔드포인트를 테스트할 때는 다음 시나리오에 대한 테스트 케이스를 포함하세요.

• 공백이 포함된 파라미터 (%20과 + 모두 테스트)
• 예약 문자(&, =, ?, #)가 포함된 파라미터
• 유니코드 문자가 포함된 파라미터
• 빈 파라미터 값
• 매우 긴 파라미터 값
• 이미 인코딩된 입력 (이중 인코딩 감지)
• 널 바이트(%00)가 포함된 파라미터