Jump to content

User:DKinzler (WMF)/REST/edit

From mediawiki.org

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"