How to Use Conditional Requests in REST APIs

Use conditional requests in REST APIs by including headers like If-None-Match or If-Modified-Since in your HTTP request. These headers let the server decide if the resource has changed and respond with 304 Not Modified to save bandwidth when data is unchanged.

Syntax

Conditional requests use special HTTP headers to ask the server if a resource has changed since the last time it was fetched.

• If-None-Match: Sends an ETag value to check if the resource has changed.
• If-Modified-Since: Sends a date to check if the resource was modified after that time.
• 304 Not Modified: Server response indicating the resource has not changed, so the client can use cached data.

http

GET /resource HTTP/1.1
Host: example.com
If-None-Match: "etag-value"

-- or --

GET /resource HTTP/1.1
Host: example.com
If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT

Example

This example shows a client requesting a resource with an If-None-Match header. The server compares the ETag and returns 304 Not Modified if the resource is unchanged.

python

import requests

url = 'https://jsonplaceholder.typicode.com/posts/1'

# First request to get the ETag
response = requests.get(url)
etag = response.headers.get('ETag')
print('First request status:', response.status_code)
print('ETag received:', etag)

# Second request with If-None-Match header
headers = {'If-None-Match': etag}
response2 = requests.get(url, headers=headers)
print('Second request status:', response2.status_code)
if response2.status_code == 304:
    print('Resource not modified, use cached data')
else:
    print('Resource modified, new data:', response2.text[:60] + '...')

Output

First request status: 200
ETag received: W/"2a-5a7f9d7f7f8a0"
Second request status: 304
Resource not modified, use cached data

Common Pitfalls

Common mistakes when using conditional requests include:

• Not handling 304 Not Modified responses properly, causing unnecessary data processing.
• Using stale or missing ETag or Last-Modified values, which breaks caching.
• Sending conditional headers with incorrect formatting or values.
• Assuming all servers support ETag or Last-Modified headers.

python

import requests

url = 'https://jsonplaceholder.typicode.com/posts/1'

# Wrong: Not checking for 304 status
headers = {'If-None-Match': 'wrong-etag'}
response = requests.get(url, headers=headers)
print('Status:', response.status_code)
print('Data length:', len(response.text))  # Always fetches data, no caching

# Right: Check for 304 and handle accordingly
if response.status_code == 304:
    print('Use cached data')
else:
    print('Update cache with new data')

Output

Status: 200
Data length: 292
Update cache with new data

Quick Reference

Header	Purpose	Example Value
If-None-Match	Check resource by ETag	"686897696a7c876b7e"
If-Modified-Since	Check resource by last modified date	Wed, 21 Oct 2015 07:28:00 GMT
ETag	Server's unique resource version identifier	"686897696a7c876b7e"
Last-Modified	Server's last modification date of resource	Wed, 21 Oct 2015 07:28:00 GMT
304 Not Modified	Server response when resource unchanged	No body, client uses cache

Key Takeaways

Use If-None-Match or If-Modified-Since headers to make conditional requests and save bandwidth.

Always check for 304 Not Modified response to use cached data instead of downloading again.

Ensure your server supports ETag or Last-Modified headers for conditional requests to work.

Handle missing or incorrect conditional headers gracefully to avoid unnecessary data fetching.

Conditional requests improve performance by reducing data transfer when resources are unchanged.