HTTP POST Parameters: Where and How

In an HTTP POST request, parameters are typically sent in the request body rather than in the request headers or URI. The request body contains the actual data being sent to the server, which can be formatted in several different ways depending on the content type specified in the headers.

Contents

• HTTP POST Request Structure
• Request Body vs Headers
• Common Body Formats
• Practical Examples
• When to Use Each Format
• Summary of Key Differences

HTTP POST Request Structure

An HTTP POST request follows a specific structure where the parameters are sent in the body:

POST /api/resource HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 123

{"key": "value", "another": "data"}

The format of an HTTP POST request is to have the HTTP headers, followed by a blank line, followed by the request body [source]. The headers contain metadata about the request, while the body contains the actual data being sent.

Request Body vs Headers

Request Body

• Primary location for POST parameters
• Contains the actual data being submitted
• Can be formatted in various ways (JSON, form-encoded, multipart)
• Size is typically limited by server configuration

Request Headers

• Not typically used for parameter values
• Contain metadata about the request
• Examples: Content-Type, Content-Length, Authorization, User-Agent
• Used to describe the body format and authentication

The request headers come before the blank line, and the body comes after the blank line [source]. While headers can contain some information, the actual parameters and data are sent in the body for POST requests.

Common Body Formats

1. JSON Format

Most common for API requests:

POST /api/login HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 47

{"email": "bob@example.com", "password": "123"}

2. application/x-www-form-urlencoded

Default for HTML forms:

POST /test HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 27

field1=value1&field2=value2

3. multipart/form-data

Used when forms include files or large amounts of data:

POST /test HTTP/1.1
Host: example.com
Content-Type: multipart/form-data; boundary="delimiter12345"

--delimiter12345
Content-Disposition: form-data; name="field1"
value1
--delimiter12345
Content-Disposition: form-data; name="field2"; filename="example.txt"
value2
--delimiter12345--

4. Text/Plain

Simple text format:

POST /api/text HTTP/1.1
Host: example.com
Content-Type: text/plain
Content-Length: 12

Hello, World!

Practical Examples

JavaScript Fetch API with JSON

const login = await fetch('https://www.example.com/api/auth/login', {
  method: 'POST',
  body: JSON.stringify({ email: 'bob@example.com', password: '123' }),
  headers: {
    'Content-Type': 'application/json',
  },
});

cURL Command Examples

JSON format:

curl -X POST https://api.example.com/data \
  -H "Content-Type: application/json" \
  -d '{"name": "John", "age": 30}'

Form-encoded format:

curl -X POST https://api.example.com/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=johndoe&password=1234"

Multipart format:

curl -X POST https://api.example.com/upload \
  -F "file=@document.pdf" \
  -F "description=Upload document"

Node.js Example

const axios = require('axios');

// JSON format
const response = await axios.post('https://api.example.com/data', {
  name: 'John',
  age: 30
}, {
  headers: {
    'Content-Type': 'application/json'
  }
});

When to Use Each Format

Use JSON When:

• Building REST APIs
• Sending structured data
• Working with JavaScript applications
• Needing complex data structures
• API documentation specifies JSON

Use application/x-www-form-urlencoded When:

• Submitting HTML forms (default)
• Sending simple key-value pairs
• Working with legacy systems
• When API documentation specifies this format
• For compatibility with older browsers

Use multipart/form-data When:

• Uploading files
• Sending mixed data types (text + files)
• Working with binary data
• Large file uploads
• When forms require file attachments

Use text/plain When:

• Sending simple text data
• Debugging purposes
• APIs that specifically require plain text
• Minimal overhead requirements

Summary of Key Differences

The choice of format depends on your use case, the requirements of the server/API, and the type of data you’re sending [source]. Modern APIs typically prefer JSON for structured data, while web forms often use the default application/x-www-form-urlencoded or multipart/form-data when files are involved.

Sources

1. How are parameters sent in an HTTP POST request? - Stack Overflow
2. POST request method - HTTP | MDN
3. HTTP Requests, body vs param vs headers vs data - Stack Overflow
4. How are Parameters Sent in an HTTP POST Request? | Sentry
5. Send parameters and body data with API requests in Postman | Postman Docs
6. Content-Type in POST Requests | Traffine I/O
7. application/x-www-form-urlencoded and multipart/form-data - RESTfm Support

Conclusion

HTTP POST requests send their parameters primarily in the request body rather than headers or URI. The body can be formatted in several ways: JSON for APIs, application/x-www-form-urlencoded for HTML forms, multipart/form-data for file uploads, and text/plain for simple text data. Understanding these different formats and when to use them is essential for proper API development and web form handling. Always check the API documentation to determine which format is expected, and ensure you set the appropriate Content-Type header to match your body format.