HTTP POST Parameters: Complete Guide

In an HTTP POST request, parameters are sent in the request body, not in the URI like GET requests. The request body contains the data formatted according to the Content-Type header specification, with common formats including application/x-www-form-urlencoded, multipart/form-data, and application/json.

Contents

• Understanding HTTP POST Parameter Location
• Request Body Formats
  • application/x-www-form-urlencoded
  • multipart/form-data
  • application/json
  • Other Body Formats
• Request Headers in POST Requests
• Comparison with GET Requests
• Practical Examples
• Best Practices

Understanding HTTP POST Parameter Location

HTTP POST requests send their parameters in the request body rather than in the URL. This is fundamentally different from GET requests, which append parameters as query strings to the URI.

The key components of an HTTP POST request are:

1. Request line (method, URI, HTTP version)
2. Headers (including Content-Type and Content-Length)
3. Body (containing the actual parameters/data)

According to the Mozilla Developer Network, the request body contains the data being sent to the server, while headers provide metadata about the request itself.

Request Body Formats

The format of the request body depends on the Content-Type header. Here are the most common formats:

application/x-www-form-urlencoded

This is the default format for HTML forms. Data is sent as key-value pairs separated by &, with keys and values URL-encoded.

Example:

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

field1=value1&field2=value2

As explained in the MDN documentation, “The default media type in a POST request is application/x-www-form-urlencoded. This is a format for encoding key-value pairs. The keys can be duplicate. Each key-value pair is separated by an & character, and each key is separated from its value by an = character.”

multipart/form-data

This format is used when sending files or binary data along with form data. Each part is separated by a boundary string.

Example:

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

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

The MDN documentation notes that “multipart/form-data is used when a form includes files or a lot of data. This request body delineates each part of the form using a boundary string.”

application/json

This format is commonly used with REST APIs and modern web applications. The body contains a JSON object.

Example:

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

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

As shown in the Sentry documentation, this format is widely used for API requests.

Other Body Formats

• text/plain: Simple text data
• application/xml: XML-formatted data
• application/octet-stream: Binary data

For example, you could use text/plain to send a plain text message in the request body of a POST request.

Request Headers in POST Requests

While parameters go in the body, headers play a crucial role in POST requests:

• Content-Type: Specifies the format of the request body
• Content-Length: Indicates the size of the request body
• Authorization: Contains authentication credentials
• User-Agent: Identifies the client software

According to HTTP messages documentation, “Headers are metadata sent with a request after the start line and before the body.”

Comparison with GET Requests

Practical Examples

JavaScript fetch() 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',
  },
});

Python requests with form data

import requests

response = requests.post(
    'https://api.example.com/submit',
    data={'key': 'value'},  # application/x-www-form-urlencoded
    headers={'Content-Type': 'application/x-www-form-urlencoded'}
)

Multipart form with file upload

const formData = new FormData();
formData.append('username', 'john');
formData.append('avatar', fileInput.files[0]);

fetch('https://api.example.com/upload', {
  method: 'POST',
  body: formData
});

Best Practices

1. Use appropriate Content-Type: Match the format to your data type
2. Include Content-Length: Helps with request processing
3. Validate input: Always validate server-side regardless of client validation
4. Use HTTPS: Especially for sensitive data
5. Consider file size: For large files, use chunked transfer encoding

Sources

1. POST request method - HTTP | MDN
2. How are parameters sent in an HTTP POST request? | Sentry
3. HTTP Requests, body vs param vs headers vs data - Stack Overflow
4. application/x-www-form-urlencoded and multipart/form-data - RESTfm Support
5. Exploring the HTTP request syntax | JetBrains

Conclusion

HTTP POST requests send their parameters in the request body rather than the URI, which differs significantly from GET requests. The body format depends on the Content-Type header, with three main formats being application/x-www-form-urlencoded (for simple form data), multipart/form-data (for files and binary data), and application/json (for APIs). Understanding these formats and when to use them is crucial for effective web development and API integration.