API:REST API/Conditional requests

This page is part of the MediaWiki REST API documentation.

Most MediaWiki REST API endpoints support conditional GET requests using ETags. ETags, short for entity tags, are unique identifiers assigned to different versions of a resource. You can use ETags to optimize your API calls when accessing the same resource multiple times.

Making a conditional request using an ETag

To make a conditional request, provide the value of the etag response header in an If-None-Match request header. If the resource has not changed since the last request, the API returns HTTP status 304 (Not Modified). If the resource has changed, the API returns HTTP status 200 (OK) with the latest data and a new ETag.

# Conditional request using If-None-Match
curl --include --header 'If-None-Match: W/"917562775"' \
https://en.wikipedia.org/w/rest.php/v1/page/Earth/history

# Response: resource unchanged
HTTP 304
etag: W/"917562775"

# Response: resource changed
HTTP 200
etag: W/"537558444"

To detect a matching resource, use the If-Match request header. If no match is found or an evaluation error occurs, the API returns a HTTP status 412 (Precondition Failed).

Making a conditional request using last-modified

When present, ETags are the preferred method for conditional requests. However, to improve API efficiency, some endpoints do not support ETags. To make a conditional request to an endpoint that doesn't return an ETag, supply the value of the last-modified response header in an If-Modified-Since or If-Unmodified-Since request header.

# Conditional request using If-Modified-Since
curl --include --header 'If-Modified-Since: Sat, 06 Jun 2020 16:38:47 GMT' \
https://en.wikipedia.org/w/rest.php/v1/page/Earth/history/counts/edits

# Response: resource unchanged
HTTP 304
content-type: application/json
last-modified: Sat, 06 Jun 2020 16:38:47 GMT

# Response: resource changed
HTTP 200
content-type: application/json
last-modified: Mon, 10 Jun 2020 06:51:35 GMT
{"count":12773,"limit":false}