User:DKinzler (WMF)/REST/edit

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

The endpoint path is:

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

Guarantees

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

Restrictions

 * 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
TBD: section edit support
 * (optional): the name of the slot to edit. Needed when editing a slot other than the main slot.
 * (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.
 * (optional): can be used if the edit is to be based on a specific revision of the page, rather than the latest revision.

Response Status
TBD: redirects for title normalization

Response Headers
TBD: ETag

TBD: Cache Contrlol

Response Body
A structure similar to a Page object as reditend by the Get Page Offline endpoint: Additional fields not defined in Page object [perhaps they should be]:

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

POST
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

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

Restrictions

 * 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

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

Request Headers
TBD: If-Match, If-Not-Modified

TBD: error message language

Request Body
A structure representing the desired new content of the page NOTE: if  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?]
 * (optional): the slot to be edited. Must match the  query parameter if both are given. Needed when editing a slot other than the main slot.
 * (required): the edit summary. [Should this be a structure with a text and a data field?] [should this be called "comment" instead?]
 * (required): the desired new content of the page, represented as HTML.
 * : TBD
 * : TBD
 * : TBD
 * : TBD
 * (optional): the data originally received in the  field of the response to the GET request.
 * (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.
 * (required if  is given): the schema URI of the original HTML as received from the GET request.Required if HTML is provided.
 * (required unless  is given and   was specified in the original GET request): the original HTML, as received from the GET request. This can be omitted if the   parameter was set in the original GET request, and the   field is given in the POST requests body.
 * (required if  is not given): the key identifying the original rendering.
 * : the underlying content model of the data being edited, as given by the original GET request. Optional on page creation.

Response
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

 * 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.