Extension:Jade/API

From mediawiki.org
Jump to navigation Jump to search

API Modules[edit]

Jade includes a number of API modules for creating and interacting with Jade Entity data:

  • jadeproposeorendorse -- Catch all, routing method that tries to *do the right thing*
  • jadecreateandendorse -- Creates a new proposal and files an endorsement.
  • jadeendorse -- Adds a new endorsement to a proposal.
  • jademoveendorsement -- Moves an endorsement to a new proposal.
  • jadedeleteproposal -- Removes a specific proposal
  • jadedeleteendorsement -- Removes the user's endorsement
  • jadesetpreference -- Moves the preference bit from one proposal to another within a facet.
  • jadeupdateproposal -- Updates the proposal notes field.
  • jadeupdateendorsement -- Updates an endorsements comments field.

All endpoints return the JSON of the entire Jade entity after applying the update.

Consult the API help docs in your local wiki for more detail. You can also view the full Jade API spec here: https://phabricator.wikimedia.org/P8830

Entity data types[edit]

In Jade, entities represent things that we might make subjective judgments about in a wiki. A page, a user, a revision, an edit, a discussion topic, a deletion proposal, etc. -- these could all be considered entities. "Entity data" is a structured representation of the entity. E.g., {"type": "revision", "id": 123456}

For example, a "revision" entity represents a complete version of a page. It is identifiable via a Revision ID number. In English Wikipedia's Jade, a revision entity for revision ID 123456 would be presented on a page with the title Jade:Revision/123456, but in other wikis, "Jade" and "Revision" may be translated to local terminology (e.g., "Yeşimi" and "Revizyon" in Turkish Wikipedia). However, the entity data representation would always be consistently as {"type": "revision", "id": 123456} and would not be localized. This provides an essential convenience for external users of our API.

Supported entities[edit]

revision
A complete version of a page. Titles appear as some localization of "Jade:Revision/<id>". Entity data matches the following schema:
{
  "type": "object",
  "properties": {
    "type": {
      "const": "revision"
    },
    "id": {
      "type": "number",
      "description": "The revision ID"
    },
    "required": ["type", "id"]
  }
}
edit (aka "Diff")
The change that results from saving a new version of a page. An edit is often represented by a single revision ID -- where the difference between the previous version and target version of the article is implied. Entity data matches the following schema:
{
  "type": "object",
  "properties": {
    "type": {
      "const": "diff"
    },
    "id": {
      "type": "number",
      "description": "The revision ID created by the edit"
    },
    "required": ["type", "id"]
  }
}

Proposed entities[edit]

item (aka "Qid" or "Wikidata item")
Any "thing" in human knowledge, including topics, concepts, and objects
{
  "type": "object",
  "properties": {
    "type": {
      "const": "item"
    },
    "id": {
      "type": "number",
      "description": "The Qid of the relevant Wikidata item"
    },
    "required": ["type", "id"]
  }
}

Label data types[edit]

Entity: Diff[edit]

Facet - editquality
Schema:
{
  "type": "object",
  "properties": {
    "damaging": {
      "type": "boolean",
      "description": "true if the edit in question represents damage to the content, false otherwise"
    },
    "goodfaith": {
      "type": "boolean",
      "description": "true if the edit appears to be well intentioned, false if the edit seems to have malicious intent"
    }
}

Entity: Revision[edit]

Facet - contentquality
Schema:
{
  "type": "number",
  "description": "An ordinal number representing a quality class where '1' is the lowest quality possible, '2' is the second lowest quality, and so on."
}

Proposed[edit]

For Entity - Diff/Facet - edittype
Schema:
{
  "type": "array",
  "items": {
    "type": "string",
    "enum": [
      "copyediting", "clarification", "simplification", "pov", "refactoring", 
      "factupdate", "elaboration", "verifiability", "disambiguation", "wikification", "process", "other"
    ]
  }
}