API talk:REST API

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!

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"?

Thanks, submitted T348546.

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.

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 task T221742

> Is the REST API part of core and is turned on by default?

Yes, and yes.

Links updated

In the infobox, you push any external link and it returns: error and redirect notice. Who updates?

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.

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,

1) Adding a table of contents

2) Retrieving pages with mobile-optimized HTML

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.

Docs updated

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}

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.

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?

API:REST API/Reference

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.

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

I don't think we intend to support other formats than JSON.