Mastering GET, POST, and File Upload Parameters with Python requests

GET Requests – Use params

GET parameters must be placed in the URL query string; the request body is ignored.

import requests

url = "https://api.example.com/users"
params = {"page": 2, "size": 10}
resp = requests.get(url, params=params)

Resulting HTTP request:

GET /users?page=2&size=10 HTTP/1.1
Host: api.example.com

Characteristics: parameters are visible, cacheable, limited by typical URL length (~2048 characters), suitable for read‑only operations such as listings or searches.

POST/PUT Requests – json vs data (Content‑Type)

POST bodies can be sent in different formats. Choose the format that matches the API’s Content‑Type contract.

json – application/json. Preferred for modern RESTful APIs.

data – application/x-www-form-urlencoded. Used for traditional HTML form submissions.

Example using json:

payload = {
    "username": "test_user",
    "email": "[email protected]",
    "roles": ["admin", "user"]
}
resp = requests.post("https://api.example.com/users", json=payload)

Requests automatically adds Content‑Type: application/json and serializes the dictionary to a JSON string. On the server side, Flask reads it with request.json and Spring reads it with @RequestBody.

Example using data for form‑encoded submission:

form_data = {"username": "test_user", "password": "secret123"}
resp = requests.post("https://api.example.com/login", data=form_data)

Requests sets Content‑Type: application/x-www-form-urlencoded and encodes the body as username=test_user&password=secret123. Flask accesses it via request.form, Spring via @RequestParam.

Common Mistakes and Debugging Tips

Mistake 1: Using data= with a JSON string. The header remains form‑urlencoded, causing the server to reject the payload (e.g., 400 Bad Request).

# Incorrect
requests.post(url, data='{"name":"Alice"}')

# Correct alternatives
requests.post(url, json={"name": "Alice"})          # preferred
# or manually set header
headers = {"Content-Type": "application/json"}
requests.post(url, data='{"name":"Alice"}', headers=headers)

Mistake 2: Supplying data or json to a GET request. The body is ignored; use params instead.

# Incorrect
requests.get(url, json={"page": 2})

# Correct
requests.get(url, params={"page": 2})

To inspect what is actually sent, print the request body and headers:

resp = requests.post(url, json=payload)
print(resp.request.body)      # request payload
print(resp.request.headers)   # includes Content‑Type

File Uploads (multipart/form‑data)

When uploading files, use the files parameter; Requests builds the multipart boundary automatically.

with open("avatar.jpg", "rb") as f:
    files = {"file": ("avatar.jpg", f, "image/jpeg")}
    resp = requests.post("https://api.example.com/upload", files=files)

Parameter‑Selection Summary

The table below maps typical use cases to the appropriate Requests argument.

Conclusion

Choosing the correct parameter style is dictated by the API’s Content‑Type contract. Use params for GET requests, json or data for POST/PUT depending on the expected format, and files for multipart uploads. Verifying the actual request payload and headers helps resolve most “parameter error” issues.