POSTMAN을 사용한다면 알아야하는 JSON 과 form-data 의 차이점과 raw JSON으로 요청하기

API를 연동할 때 요청 데이터 형식을 선택하는 것은 매우 중요합니다.

새로 이직한 회사에서, POSTMAN을 주로 사용하고 있습니다.

"null 값이 허용되지 않는다,text plain 가 지원되지 않는 미디어 형태입니다" 등의 에러가 발생한다는 제보가 있어서,
text form-data 와 JSON 방식의 차이를 간단하게 설명해드린 일이 있었습니다.

공유한 내용을 보완하여 기록합니다.

요즘 현대적인 RestfulAPI를 사용하는 프론트엔드와 백엔드 간의 통신에서는 JSON(application/json)이 기본적으로 사용됩니다.

하지만 특정한 경우에는 form-data(multipart/form-data)를 사용해야 합니다.

이번 글에서는 API 요청 시 JSON과 form-data의 차이점과 적절한 사용 사례를 설명하겠습니다.

목차

1. JSON과 form-data의 차이점

JSON (application/json)

JSON의 특징

요즘은 비개발자분들도 너무 잘 알고 있는 데이터 형식, JSON(JavaScript Object Notation) 입니다.

• 데이터를 객체({})와 배열([]) 형태로 표현할 수 있습니다.
• null, 숫자, 문자열, 불리언과 같은 다양한 데이터 타입을 지원합니다.

개발자라면 눈여겨봐야 할 것은, 바로 Content-Type이 application/json으로 설정된다는 것 입니다.

JSON의 예시

{
  "username": "user1",
  "age": 25,
  "email": "user1@example.com",
  "preferences": {
    "notifications": true,
    "theme": "dark"
  }
}

이처럼 JSON은 계층 구조를 가지며, 객체와 배열을 자유롭게 포함할 수 있습니다.

form-data (multipart/form-data)

form-data는 파일 업로드를 지원하는 HTTP 요청 형식입니다.
주로 HTML 폼 제출 시 사용되며, 데이터를 여러 부분으로 나누어 전송하는 Multipart 형식을 가집니다.

form-data의 특징

• 키-값 쌍(key=value) 형태로 데이터를 전송하며, 가장 큰 장점은 파일(Binary 데이터)을 포함할 수 있다는 것 입니다.
• 하지만, null 값을 명확하게 표현할 수 없으며, 이를 빈 문자열("")로 대체하는 경우가 많습니다.

Content-Type은 json 과 다르게 multipart/form-data로 설정되며, formData 형식으로 프론트엔드 요청시에는 대부분의 header를 브라우저가 자동 Content-Type 세팅을 해주기 때문에, 이 부분을 고려하지는 않아도 됩니다.

form-data의 예시

form-data
├── username (text) : user1
├── age (text) : 25
├── profile_picture (file) : image.jpg # 이렇게 이미지를 넣어서 요청을 보낼 수 있다는 것이 장점 입니다.

2. JSON과 form-data의 차이점 정리

구분	JSON (application/json)	form-data (multipart/form-data)
데이터 구조	객체 및 배열 지원	단순한 키-값 쌍
파일 업로드	❌ 지원하지 않음	✅ 지원 가능
null 값 표현	✅ 지원 ("key": null)	❌ 지원하지 않음 (빈 값 처리)
데이터 직렬화	✅ JSON.stringify() 가능	❌ 직접 직렬화 필요
전송 속도	상대적으로 빠름	상대적으로 느림

그렇기 때문에,
API 요청 시 JSON을 사용하면 데이터 표현이 비교적 자유롭습니다.
* JSON은 객체와 배열을 지원하므로 계층 구조를 표현할 수 있으며, null, 불리언 등 다양한 데이터 타입을 포함할 수 있습니다.

3. form-data를 사용 하는 경우

form-data는 일반적인 API 요청에는 적합하지 않지만, WAS로 파일을 전달할 때 사용합니다.
하지만 만약 AWS S3를 사용한다면, presignURL 을 사용하는 방법이 훨씬 효율적이라고 생각합니다.

이제 API 요청 시 어떤 데이터 형식을 선택해야 하는지 명확하게 이해할 수 있을 것입니다.

4. POSTMAN 에서 raw로 JSON 형식 요청하기

아래는 POSTMAN에서 Text/File 중의 형식을 고를 수 있는 form-data 탭입니다.

null 값을 보내고 싶다면, JSON으로 요청하면 됩니다.

그러기 위해서는 raw탭에서 요청을 진행해야합니다.

하지만 그냥 발송하게 되면 아래 에러를 만나게 됩니다.

415 Unsupported Media Type 에러

{

"detail": "요청된 \"text/plain\"가 지원되지 않는 미디어 형태입니다."

}

415 Unsupported Media Type 에러가 발생합니다.

The media format of the requested data is not supported by the server.

이는 JSON 이 아닌 Text로 발송했기 때문입니다.

탭의 우측 맨 오른쪽에 Text라고 되어있는 곳이 있습니다.

이곳에서 JSON을 선택 후 API를 발송해야 합니다.

이 해당 이슈는 약 3년 전 쯤, POSTMAN을 처음 사용하며 경험한 이슈였는데,

주변에서 이 이슈를 겪는 것을 보니 예전 생각이 많이 났습니다.