API talk:REST API

Doc review: conditional requests

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

Hi @NNikkhoui (WMF), Here's the section about conditional requests that I'd like to add to this doc once the page endpoints are moved into v1. Please review! (PS: Looks like the JSON spacing and syntax highlighting are weird in this preview, so disregard that.)

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 the same resource. You can use an ETag value with the If-None-Match header to optimize your API calls when accessing the same resource multiple times.

Here's an example of an ETag returned by the get HTML endpoint:

# Retrieve information about the Pinnation page on English Wikipedia
$ curl --include https://en.wikipedia.org/w/rest.php/v1/page/Pinnation/bare

HTTP 200
content-type: application/json
etag: W/"917562775"
{
"id": 339742,
"key": "Pinnation",
"title": "Pinnation",
"latest": {
"id": 917562775,
"timestamp": "2019-09-24T11:43:46Z"
},
"content_model": "wikitext",
"license": {
"url": "//creativecommons.org/licenses/by-sa/3.0/",
"title": "Creative Commons Attribution-Share Alike 3.0"
},
"html_url": "https://en.wikipedia.org/w/rest.php/v1/page/Pinnation/html"
}

A conditional request allows you to shortcut subsequent requests for the same resource by comparing the ETag value provided with the If-None-Match 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/Pinnation/bare

# Response: resource unchanged
HTTP 304
content-type: application/json
etag: W/"917562775"

# Response: resource changed
HTTP 200
content-type: application/json
etag: W/"537558444"
{
"id": 339742,
"key": "Pinnation",
"title": "Pinnation",
"latest": {
"id": 537558444,
"timestamp": "2020-01-25T20:03:40Z"
},
"content_model": "wikitext",
"license": {
"url": "//creativecommons.org/licenses/by-sa/3.0/",
"title": "Creative Commons Attribution-Share Alike 3.0"
},
"html_url": "https://en.wikipedia.org/w/rest.php/v1/page/Pinnation/html"
}

Conditional requests with If-Modified-Since

When present, ETags and If-None-Match headers are the preferred method for conditional requests. However, to improve API efficiency in certain cases, some endpoints don't support ETags. To make a conditional request to an endpoint that doesn't return an ETag, use the last-modified value with the If-Modified-Since header.

Here's an example of an endpoint that returns only a last-modified value:

# Get the number of edits to the Pinnation page on English Wikipedia
$ curl --include https://en.wikipedia.org/w/rest.php/v1/page/Pinnation/history/counts/edits

HTTP 200
content-type: application/json
last-modified: Tue, 24 Sep 2019 11:43:46 GMT
{"count":115,"limit":false}

To make a conditional request, include the last-modified value with the If-Modified-Since 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 last-modified timestamp.

# Conditional request using If-Modified-Since
curl --include \
--header 'If-Modified-Since: Tue, 24 Sep 2019 11:43:46 GMT' \
https://en.wikipedia.org/w/rest.php/v1/page/Pinnation/history/counts/edits

# Response: resource unchanged
HTTP 304
content-type: application/json
last-modified: Tue, 24 Sep 2019 11:43:46 GMT

# Response: resource changed
HTTP 200
content-type: application/json
last-modified: Mon, 11 Jan 2020 06:51:35 GMT
{"count":117,"limit":false}
APaskulin (WMF) (talk) 21:03, 20 February 2020 (UTC)
It looks great! A few possible things to consider mentioning.
  • You could mentioned "max-age" header. "max-age" is a response header set set by the API, and without it none of the other conditional request headers will kick in. Max-age tells the browser to cache the response for X number of seconds, and then after that the other headers you mentioned above will kick in. The default max-age right now is supposed to be 60 seconds (according to some comments on https://phabricator.wikimedia.org/T238374) but i think some endpoints like PageSourceHandler have it set to 5 sec. For that, maybe its worth noting here the default value and then on a per-endpoint basis you could mention "This endpoint is an exception with max-age of X sec"?
  • We return 412 HTTP response sometimes too, if there was something wrong with the precondition e.g. you send an "If-Unmodified-Since" header in a POST and the last modified time of the resource you are changing is greater than the "If-Unmodified-Since" timestamp.
  • The "If-Match" and "If-Unmodified-Since" headers
    • The ConditionalHeaderUtil class supports these, so should be worth noting i think
  • "However, to improve API efficiency in certain cases" - I think the wording on this one could be ever so slightly more specific to say what exactly is more efficient? You could say that Etag are not used when the level of effort in determining the Etag is seen as more costly than the benefit it provides. For example, In the PageHistoryCountHandler, we would need to hit the database to get visibility settings of the page the user is searching for and work that value into the Etag. Since that requires a database hit, and the payload that comes back is pretty small (we're not saving much on sending data across the wire) it didn't seem worth it to use Etags in that case.

NNikkhoui (WMF) (talk) 19:11, 24 February 2020 (UTC)
Thank you! I've published an updated version to API:REST API/Conditional requests. Edits welcome!
Regarding max-age and database efficiency considerations, I was thinking that it might be helpful to create a REST API implementers' guide that includes this type of information. That would help us separate docs for people who want to use the API as opposed to people who are interested in the inner workings of the API. What do you think? APaskulin (WMF) (talk) 00:42, 16 June 2020 (UTC)
The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Content negotiation support?

For MediaWiki pages to get the gist of information it would be nice to have content negotation which would provide the meta-data of the page e.g. it's wikipedia id - it's markup - the pictures in the page and the like in the format requested e.g. XML, JSon,RDF ... Are there any plans for such a feature? @Seppl2013 Seppl2013 (talk) 14:06, 4 May 2020 (UTC)

I don't think we intend to support other formats than JSON. EProdromou (WMF) (talk) 17:16, 6 May 2020 (UTC)

Is there a place to see all API endpoints?

RESOLVED
API:REST API/Reference

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

I've picked up on a couple endpoints by reading through the docs such as `html`, and `bare`, but I'm wondering if there's a place to see all the endpoints. Tlietz (talk) 14:08, 15 December 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Are there plans to support any of the following?

1) Adding a table of contents

2) Retrieving pages with mobile-optimized HTML Tlietz (talk) 19:44, 15 December 2022 (UTC)

Hi @Tlietz, There is no dedicated endpoint for adding a table of contents, but you can use the update page endpoint to modify a page and add a table of contents. (Tables of contents are added automatically to pages with more than 3 headings, but you can change the location of the table of contents on the page, as well as a few other attributes. See Manual:Table of contents for more information.)
Currently, only the Wikimedia REST API offers an endpoint for retrieving mobile-optimized HTML. APaskulin (WMF) (talk) 15:55, 19 December 2022 (UTC)
RESOLVED
Links updated

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

In the infobox, you push any external link and it returns: error and redirect notice. Who updates? Omotecho (talk) 08:45, 17 March 2023 (UTC)

Hi @Omotecho. Thanks for pointing this out! I've updated Template:REST API and API:REST API/Reference with the new links. It might take some time for the updates from the template to appear on API:REST API, so in the meantime you can use the links on API:REST API/Reference. APaskulin (WMF) (talk) 15:41, 17 March 2023 (UTC)
So thankful for your crisp reply (: We editors can rely on you to work and expand what we have on each project, dōmō arigatō, appreciate very much and I'll work on the /Reference page. Cheers, Omotecho (talk) 15:52, 17 March 2023 (UTC)
The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

REST API vs Action API

What's the differences between the REST API and the Action API? I am mostly familiar with the Action API. Why are there two? Do they use the same actions? Is there a Special:ApiSandbox for the REST API? Is the REST API part of core and is turned on by default? Thanks. –Novem Linguae (talk) 01:02, 8 June 2023 (UTC)

Core_Platform_Team/Initiatives/Core_REST_API_in_MediaWiki and subpages/linked phab tasks might explain some of this.
> Is there a Special:ApiSandbox for the REST API?
See T221742
> Is the REST API part of core and is turned on by default?
Yes, and yes. KHarlan (WMF) (talk) 12:53, 8 June 2023 (UTC)

Getting 'The "q" parameter must be set.'

When using the REST API to search on my wiki (yi.hamichlol.org.il), whether content or titles, I'm always getting the "missingparam" failureCode - although the q paramater clearly is set. See:

/w/rest.php/v1/search/title?q=b&limit=10

/w/rest.php/v1/search/page?q=b&limit=10

Other endpoints, which don't use the 'q' parameter, work just fine. Such as:

/w/rest.php/v1/page/11/bare

Anything I can do to get search results via REST? Thanks! צמא לדעת (talk) 07:25, 3 October 2023 (UTC)

Hi @צמא לדעת, This definitely looks like a bug in the API. Can you submit a bug report for this and tag it with "MediaWiki-REST-API" and "API Platform"? APaskulin (WMF) (talk) 21:57, 4 October 2023 (UTC)
Thanks, submitted T348546. צמא לדעת (talk) 15:47, 10 October 2023 (UTC)

Feedback requested on proposed revision to REST API docs

As part of a WMF annual plan focus on standardizing our APIs, the Wikimedia Technical Documentation team has been working on defining how we can implement some best practices for API documentation. One of our goals is to make the documentation experience as consistent as possible across APIs, so that it's easier to find information and navigate docs even if they live on different wikis.

As a first step towards standardizing on-wiki API documentation, I've created a draft revision for the MediaWiki REST API docs: User:TBurmeister_(WMF)/Sandbox/REST_API.

  • A list of the changes included in this revision and the reasoning behind them is in phab:T405972.
  • Note that the revised version includes all the information currently in these docs (if it's still correct), along with some new content.
  • The main change is to the structure of the pages and which pieces of information are presented together.
  • In addition to providing a more navigation-focused landing page for these docs, I would keep and update Template:REST_API to support navigation between subpages. (I just didn't want to create a new template only for my Sandbox version of the docs).

Feedback on this proposed revision is welcome as comments on this topic thread, as comments on my Sandbox pages, or on phab:T405972. Thank you! TBurmeister (WMF) (talk) 20:18, 20 November 2025 (UTC)

I've just completed major content revisions to API:REST_API and Template:REST_API, and I added new pages API:REST_API/Get_started and API:REST_API/Policies. Also some minor changes to API:REST_API/Reference. Wherever possible, I kept the existing translation units, but especially for API:REST_API since the old content is significantly rewritten, or was moved to an entirely new page, I think that page should be marked-up for translation as if it were mostly new.
All the currently-planned major revisions to these pages are now complete. For reference,phab:T405972 is the tracking task for this work. TBurmeister (WMF) (talk) 19:43, 8 December 2025 (UTC)