API:REST API/Conditional requests

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.

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
HTTP304
etag:W/"917562775"
# Response: resource changed
HTTP200
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).

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: 2020年6月06日 16:38:47 GMT'\
https://en.wikipedia.org/w/rest.php/v1/page/Earth/history/counts/edits
# Response: resource unchanged
HTTP304
content-type:application/json
last-modified:Sat,06Jun202016:38:47GMT
# Response: resource changed
HTTP200
content-type:application/json
last-modified:Mon,10Jun202006:51:35GMT
{"count":12773,"limit":false}