Python requests module: How to POST JSON data

Introduction

Learn how to use the Python requests module to POST JSON data to a web server, an essential skill for web-based APIs interaction.

Getting Started with POST Requests

Before diving into posting JSON, ensure you have the requests library installed:

pip install requests

To send a basic POST request with JSON data, you’ll need to import the requests module and use the post method:

import requests

data = {'key': 'value'}
response = requests.post('https://api.example.com/data', json=data)
print(response.text)

This will send a request with JSON data to the specified URL and output the server’s response.

Headers and Content Types

It’s important to set the right header for your request. Typically, JSON data is sent with a Content-Type of application/json:

headers = {'Content-Type': 'application/json'}
response = requests.post('https://api.example.com/data', headers=headers, json=data)

If you manually convert your data to a JSON string, use the data parameter instead of json:

import json

json_data = json.dumps({'key': 'value'})
response = requests.post('https://api.example.com/data', headers=headers, data=json_data)

Error Handling

When working with POST requests, it’s vital to handle potential errors:

try:
    response = requests.post('https://api.example.com/data', json=data)
    response.raise_for_status()
except requests.exceptions.HTTPError as err:
    raise SystemExit(err)

This code will raise an exception if the POST request does not succeed, allowing you to deal with errors appropriately.

Working with Response Data

Once you’ve made a successful POST request, you may want to work with the JSON data returned from the server:

if response.status_code == 200:
    results = response.json()
    print(results)

This converts the response text to a Python dictionary if the response is OK (status code 200).

Authenticating with APIs

Some APIs require authentication. Here’s how to include basic auth with your POST requests:

from requests.auth import HTTPBasicAuth

auth = HTTPBasicAuth('username', 'password')
response = requests.post('https://api.example.com/data', auth=auth, json=data)

If the API uses token-based authentication, include the token in the headers:

headers = {'Authorization': 'Token YOUR_API_TOKEN'}
response = requests.post('https://api.example.com/data', headers=headers, json=data)

Handling Sessions and Cookies

If you need to maintain a session or handle cookies, you can use a requests session object:

with requests.Session() as session:
    session.post('https://api.example.com/login', json={'username': 'user', 'password': 'pass'})
    response = session.post('https://api.example.com/data', json=data)
    print(response.text)

This will handle cookies and maintain your login session for subsequent requests.

Advanced JSON POST Requests

For more complex requirements, such as sending nested JSON data or including additional form data or files, Here’s an example of a more complex POST request:

files = {'file': ('report.csv', open('report.csv', 'rb'), 'text/csv', {'Expires': '0'})}
additional_data = {'key': 'value', 'json': json.dumps({'nested': 'json'})}
response = requests.post('https://api.example.com/submit', files=files, data=additional_data)

This sends a multipart/form-data request, including a file and nested JSON.

Conclusion

Post JSON data with Python’s requests module provides a comprehensive method for interacting with web APIs. Through advancing from foundational knowledge to handling sessions and mastering complex data structures you can fully leverage the power of networked applications.