content.yaml

swagger: '2.0'
info:
  version: '1.0.0'
  title: mediawiki content api
  description: basic mediawiki content api.
  termsofservice: https://github.com/wikimedia/restbase#restbase
  contact:
    name: services
    email: services@lists.wikimedia.org
    url: https://www.mediawiki.org/wiki/services
  license:
    name: gnu affero
    url: http://opensource.org/licenses/agpl-3.0

paths:

  /{module:page}/:
    get:
      tags:
        - Page content
      description: List pages
      x-backend-request:
        uri: /{domain}/sys/page_revisions/page/

  /{module:page}/{title}:
    get:
      tags:
        - Page content
      description: Redirect to the latest HTML for this page
      # TODO
      # x-backend-request:
      #   uri: /{domain}/sys/page_revisions/page/

  /{module:page}/{title}/:
    get:
      tags:
        - Page content
      description: List available content types for a page
      produces:
        - application/json

  /{module:page}/{title}/html:
    get:
      tags:
        - Page content
      description: Retrieve the latest html
      operationId: getLatestFormat
      parameters:
        - name: domain
          in: path
          description: The domain under which the data resides
          type: string
          required: true
          default: en.wikipedia.org
        - name: title
          in: path
          description: the title of page content
          type: string
          required: true
      responses:
        '302':
          description: redirection to the latest html
        '404':
          description: unknown table, bucket, or domain
          schema:
            $ref: '#/definitions/notfound'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/defaulterror'
      x-backend-request:
        # Directly return the latest HTML. Alternatively, we could also try
        # relative redirects. A relative location header of 'foo/bar' seems to
        # work in current Chrome and Firefox.
        # See also http://tools.ietf.org/html/rfc7231#section-7.1.2
        uri: /{domain}/sys/parsoid/html/{title}/latest

  /{module:page}/{title}/html/:
    get:
      tags:
        - Page content
      description: List all HTML revisions for a page
      operationId: listKeyRevValueRevisions
      produces:
        - application/json
      parameters:
        - name: domain
          in: path
          description: The domain under which the data resides
          type: string
          required: true
          default: en.wikipedia.org
        - name: title
          in: path
          description: The title of page content
          type: string
          required: true
      responses:
        '200':
          description: The list of revisions
          schema:
            type: array
            items:
              $ref: '#/definitions/revisions'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/defaultError'
      x-backend-request:
        uri: /{domain}/sys/parsoid/html/{title}/


  /{module:page}/{title}/html/{revision}{/tid}:
    get:
      tags:
        - Page content
      description: Retrieve the html for a given revision (and optional timeuuid)
      operationId: getFormatRevision
      produces:
        - text/html
      parameters:
        - name: domain
          in: path
          description: The domain under which the data resides'
          type: string
          required: true
          default: en.wikipedia.org
        - name: title
          in: path
          description: The title of page content
          type: string
          required: true
        - name: revision
          in: path
          description: The revision
          type: string
          required: true
      responses:
        '200':
          description: The latest html for the given page
        '400':
          description: Invalid revision
          schema:
            $ref: '#/definitions/invalidRevision'
        '404':
          description: Unknown table, bucket, page, or domain
          schema:
            $ref: '#/definitions/notFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/defaultError'
      x-backend-request:
        uri: /{domain}/sys/parsoid/html/{title}/{revision}{/tid}
        headers:
          cache-control: $req.headers.cache-control

  /{module:page}/{title}/data-parsoid:
    get:
      tags:
        - Page content
      description: Retrieve the latest data-parsoid (private Parsoid metadata)
      parameters:
        - name: domain
          in: path
          description: The domain under which the data resides
          type: string
          required: true
          default: en.wikipedia.org
        - name: title
          in: path
          description: the title of page content
          type: string
          required: true
      responses:
        200:
          description: data-parsoid JSON blob
        '404':
          description: unknown table, bucket, or domain
          schema:
            $ref: '#/definitions/notfound'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/defaulterror'
      x-backend-request:
        # Directly return the latest HTML. Alternatively, we could also try
        # relative redirects. A relative location header of 'foo/bar' seems to
        # work in current Chrome and Firefox.
        # See also http://tools.ietf.org/html/rfc7231#section-7.1.2
        uri: /{domain}/sys/parsoid/data-parsoid/{title}/latest

  /{module:page}/{title}/data-parsoid/:
    get:
      tags:
        - Page content
      description: List data-parsoid revisions for a page
      produces:
        - application/json
      parameters:
        - name: domain
          in: path
          description: The domain under which the data resides
          type: string
          required: true
          default: en.wikipedia.org
        - name: title
          in: path
          description: The title of page content
          type: string
          required: true
      responses:
        '200':
          description: The list of revisions
          schema:
            type: array
            items:
              $ref: '#/definitions/revisions'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/defaultError'
      x-backend-request:
        uri: /{domain}/sys/parsoid/data-parsoid/{title}

  /{module:page}/{title}/data-parsoid/{revision}{/tid}:
    get:
      tags:
        - Page content
      description: Retrieve data-parsoid (internal Parsoid metadata) for a given page & revision
      operationId: getFormatRevision
      produces:
        - text/html
      parameters:
        - name: domain
          in: path
          description: The domain under which the data resides'
          type: string
          required: true
          default: en.wikipedia.org
        - name: title
          in: path
          description: The title of page content
          type: string
          required: true
        - name: revision
          in: path
          description: The revision
          type: string
          required: true
      responses:
        '200':
          description: The latest Parsoid data for the given page
        '400':
          description: Invalid revision
          schema:
            $ref: '#/definitions/invalidRevision'
        '404':
          description: Unknown table, bucket, page, or domain
          schema:
            $ref: '#/definitions/notFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/defaultError'
      x-backend-request:
        uri: /{domain}/sys/parsoid/data-parsoid/{title}/{revision}{/tid}
        headers:
          cache-control: $req.headers.cache-control
              

  /{module:transform}/html/to/wikitext{/title}{/revision}:
    post:
      tags:
        - Transforms
      description: Transform HTML to wikitext
      consumes:
        - multipart/form-data
      produces:
        - text/plain; profile=mediawiki.org/specs/wikitext/1.0.0
      parameters:
        - name: domain
          in: path
          description: The top-level API domain
          type: string
          required: true
          default: en.wikipedia.org
        - name: title
          in: path
          description: The page title
          type: string
          required: false
        - name: revision
          in: path
          description: The page revision
          type: integer
          required: false
        - name: html
          in: formData
          description: The HTML to transform
          type: string
          required: true
      x-backend-request:
        uri: /{domain}/sys/parsoid/transform/html/to/wikitext{/title}{/revision}

  /{module:transform}/wikitext/to/html{/title}{/revision}:
    post:
      tags:
        - Transforms
      description: Transform wikitext to HTML
      consumes:
        - multipart/form-data
      produces:
        - text/html; profile=mediawiki.org/specs/html/1.0.0
      parameters:
        - name: domain
          in: path
          description: The top-level API domain
          type: string
          required: true
          default: en.wikipedia.org
        - name: title
          in: path
          description: The page title
          type: string
          required: false
        - name: revision
          in: path
          description: The page revision
          type: integer
          required: false
        - name: wikitext
          in: formData
          description: The Wikitext to transform to HTML
          type: string
          required: true
        - name: bodyOnly
          in: formData
          description: Return only `body.innerHTML`
          type: boolean
          required: false
      x-backend-request:
        uri: /{domain}/sys/parsoid/transform/wikitext/to/html{/title}{/revision}

  /{module:transform}/html/to/html{/title}{/revision}:
    post:
      tags:
        - Transforms
      description: Update / refresh / sanitize HTML
      consumes:
        - multipart/form-data
      produces:
        - text/html; profile=mediawiki.org/specs/html/1.0.0
      parameters:
        - name: domain
          in: path
          description: The top-level API domain
          type: string
          required: true
          default: en.wikipedia.org
        - name: title
          in: path
          description: The page title
          type: string
          required: false
        - name: revision
          in: path
          description: The page revision
          type: integer
          required: false
        - name: html
          in: formData
          description: The HTML to transform
          type: string
          required: true
        - name: bodyOnly
          in: formData
          description: Return only `body.innerHTML`
          type: boolean
          required: false
      x-backend-request:
        uri: /{domain}/sys/parsoid/transform/html/to/html{/title}{/revision}

definitions:
  defaultError:
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
  invalidRevision:
    required:
      - code
      - method
      - title
      - type
      - uri
    properties:
      code:
        type: integer
        format: int32
      method:
        type: string
      title:
        type: string
      type:
        type: string
      uri:
        type: string
  notFound:
    required:
      - code
      - method
      - title
      - type
      - uri
    properties:
      code:
        type: integer
        format: int32
      type:
        type: string
      title:
        type: string
      description:
        type: string
      localURI:
        type: string
      table:
        type: string
      uri:
        type: string
      method:
        type: string
  revisions:
    required:
      - items
    properties:
      items:
        type: array
        items:
          type: string