Submit a URL-encoded form

`application/x-www-form-urlencoded`로 폼 데이터를 보내는 레시피입니다. 전통적인 HTML 폼 전송과 OAuth 토큰 엔드포인트 등에서 씁니다.

개요

`application/x-www-form-urlencoded`로 폼 데이터를 보내는 레시피입니다. 전통적인 HTML 폼 전송과 OAuth 토큰 엔드포인트 등에서 씁니다.

코드로 보기

# --data-urlencode encodes special characters (spaces, &, =) safely:
curl -X POST https://example.com/login \
  --data-urlencode 'user=alice' \
  --data-urlencode 'note=hello world & more'
# Content-Type: application/x-www-form-urlencoded (default for -d)
const body = new URLSearchParams({
  user: 'alice',
  note: 'hello world & more'
});
await fetch('https://example.com/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body // URLSearchParams stringifies + encodes for you
});
import requests

# passing a dict as data= sends x-www-form-urlencoded and encodes values
res = requests.post('https://example.com/login',
                    data={'user': 'alice', 'note': 'hello world & more'})

설명

이 형식은 `key=value&key2=value2` 형태로 값을 잇고, 특수문자는 퍼센트 인코딩합니다. curl에서 `-d`(=`--data`)는 값을 인코딩하지 않고 그대로 보내므로 공백·`&`·`=`가 있으면 깨집니다. 반드시 값을 인코딩하는 `--data-urlencode`를 필드마다 쓰세요.

`fetch`에서는 `URLSearchParams`가 인코딩과 문자열화를 자동 처리하며, body로 넘기면 브라우저가 Content-Type도 채워 줍니다. `requests`는 `data=`에 딕셔너리를 주면 자동으로 이 형식으로 인코딩합니다(JSON을 보내려면 `json=`).

이 방식은 파일 전송에 부적합합니다(멀티파트 사용). 또한 배열·중첩 객체 표현이 표준화되어 있지 않아 서버 규약에 따라 `key[]=a&key[]=b` 등으로 달라지므로, 복잡한 구조는 JSON POST가 더 명확합니다.

관련 헤더

Content-TypeContent-Length

관련 상태코드

200OK302Found400Bad Request422Unprocessable Content