MediaWiki

User:DKinzler (WMF)/REST/edit

< User:DKinzler (WMF)

The WYSIWYG API provides andpoints that allows a page's content to edited using manipulation of HTML.

The endpoint path is: page/{title}/wysiwyg

GET page/{title}/wysiwyg

edit

This returns the current content of the page as HTML, wrapped in a JSON structure that contains meta-data.

Guarantees

edit
  • The response will reflect the current state of the primary database server. Caches are bypassed.

Restrictions

edit
  • the request will fail if the client does not have permission to view or edit the page
  • the edit rate limit will be checked and the request will fail if the limit has been exceeded
  • the primary server read rate limit will be bumped and the request will fail if the limit has been exceeded

Query Parameters

edit
  • slot (optional): the name of the slot to edit. Needed when editing a slot other than the main slot.
  • stash (optional): Maintain some state on the server side, to reduce the amount of data to be send to the client and later back to the server. When that state expires, the edit will fail.
  • revision (optional): can be used if the edit is to be based on a specific revision of the page, rather than the latest revision.

TBD: section edit support

Response Status

edit

TBD: redirects for title normalization

Response Headers

edit

TBD: ETag

TBD: Cache Contrlol

Response Body

edit

A structure similar to a Page object as reditend by the Get Page Offline endpoint:

{
  "slot": "main",
  "page": {
    "id": 9228,
    "key": "Earth",
    "title": "Earth",
    "url": "https://api.wikimedia.org/core/v1/wikipedia/en/page/Earth"
  },
  "license": {
    "url": "//creativecommons.org/licenses/by-sa/3.0/",
    "title": "Creative Commons Attribution-Share Alike 3.0"
  },
  "rendering": {
    "revision": 963613515,
    "schema": "https://www.mediawiki.org/wiki/Specs/data-parsoid/2.4.0",
    "key": "963613515.main/6e0b9658-2462-11ed-9fdd-4cd98faf426e/edit/stash",
    "html": "<!DOCTYPE html><html>...<html>"
    "content_model": "wikitext" 
  }
}

Additional fields not defined in Page object [perhaps they should be]:

  • page: meta data about the page that is being edited. Contains the following:
    • id: the page ID
    • title: the page's title in human readable form, as used in wikitext links.
    • key: the page's title in URL form (normalized but unencoded).
    • url: the URL of the meta data nedpoint for the page
  • rendering: a structure containing information about a specific rendering of the page
    • schema: the schema of the HTML.
    • key: a unique idenifier of the specific rendering returned in the htmlfield.
    • html: the rendered HTML representation of the page.
    • content_model: the underlying content model of the data being edited.
    • revision: the revision ID of the content that was rendered
  • slot: the name of the slot being edited, if it's not the main slot. Matches the slot query parameter.
  • TBD: notices (optional)
  • TBD: templates used (optional)

TBD: error response structure

POSTpage/{title}/wysiwyg

edit

This submits the new HTML of the page, wrapped in a JSON structure that contains meta-data. Can be used to create or update the page.

Guarantees

edit
  • If the response has a status in the 2xx or 3xx range, the page was updated.

Restrictions

edit
  • the request will fail if the client does not have permission to view or edit the page
  • the edit rate limit will be bumped and the request will fail if the limit has been exceeded

Query Parameters

edit
  • slot (optional): the name of the slot to edit. Must match the slot field in the request body, if both are given.

Request Headers

edit

TBD: If-Match, If-Not-Modified

TBD: error message language

Request Body

edit

A structure representing the desired new content of the page

{
  "slot": "main",
  "summary": "copy edit",
  "html": "<!DOCTYPE html><html>...<html>"
  "original": {
    "revision": 963613515,
    "schema": "https://www.mediawiki.org/wiki/Specs/data-parsoid/2.4.0",
    "key": "963613515.main/6e0b9658-2462-11ed-9fdd-4cd98faf426e/edit/stash",
    "html": "<!DOCTYPE html><html>...<html>"
    "content_model": "wikitext" 
  }
}
  • slot(optional): the slot to be edited. Must match the slot query parameter if both are given. Needed when editing a slot other than the main slot.
  • summray(required): the edit summary. [Should this be a structure with a text and a data field?] [should this be called "comment" instead?]
  • html(required): the desired new content of the page, represented as HTML.
  • watch: TBD
  • minor: TBD
  • bot: TBD
  • tags: TBD
  • original(optional): the data originally received in the rendering field of the response to the GET request.
    • revision(required): the ID of the revision the edit is based on. If the page did not previously exist and should be created, this should be set to 0. Concurrent creation will then result in failure.
    • schema(required if html is given): the schema URI of the original HTML as received from the GET request.Required if HTML is provided.
    • html(required unless key is given and stash was specified in the original GET request): the original HTML, as received from the GET request. This can be omitted if the stash parameter was set in the original GET request, and the key field is given in the POST requests body.
    • key (required if html is not given): the key identifying the original rendering.
    • content_model: the underlying content model of the data being edited, as given by the original GET request. Optional on page creation.

NOTE: if original is omitted, the page will be created if it doesn't exist, and it will be blindly updated if it does exist: no conflict detection applies, concurrent edits will be overwritten. [do we even want to allow this?]

Response

edit

TBD: On success, a redirect to the new content of the page?!

TBD: indicate that conflict resolution was applied?

TBD: indicate a null edit?

Differences from the v1 page endpoints

edit
  • No stale content will be returned, response is up to date with the primary database
  • Edit permissions are checked on GET
  • No support for html2html transformations such as language variants and other flavors.
  • Support for slots (frees up the v1 endpoint to return combined content of multiple slots)
  • Proper modeling of edit summaries
  • Support for contextual information like notices to the user, lists of templates or media used, etc
  • Does not use the PUT verb, since MW edits do not replace a resource verbatim.

POST page/{title}/to/html

edit

TBD. Similar to transform/from/wikitext/to/html

POST page/{title}/from/html

edit

TBD. Similar to transform/from/html/to/wikitext

Retrieved from "https://www.mediawiki.org/w/index.php?title=User:DKinzler_(WMF)/REST/edit&oldid=5449382"