swagger: '2.0'
info:
  version: '1.0.0-beta'
  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: Apache licence, v2
    url: https://www.apache.org/licenses/LICENSE-2.0
tags:
  - name: Transforms
    description: convert content between HTML and Wikitext
paths:
  /html/to/wikitext{/title}{/revision}:
    post:
      tags:
        - Transforms
      summary: Transform HTML to Wikitext
      description: |
        Transform [Parsoid HTML](https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec)
        to Wikitext.

        When converting pre-existing (possibly modified) content, you should
        pass in the `title`, `revision`, and `If-Match` header. This lets
        [Parsoid](https://www.mediawiki.org/wiki/Parsoid) preserve small
        syntactic variations in wikitext, which ensures that diffs are
        readable.

        - Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable)
        - Rate limit: 5 req/s
      consumes:
        - multipart/form-data
      produces:
        - text/plain; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/wikitext/1.0.0"
      parameters:
        - name: title
          in: path
          description: "Page title. Use underscores instead of spaces. Example: `Main_Page`."
          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-textarea: true
        - name: scrub_wikitext
          in: formData
          description: Normalise the DOM to yield cleaner wikitext?
          type: boolean
          required: false
        - name: if-match
          in: header
          description: |
            The `ETag` header of the original render indicating it's revision and timeuuid.
            Required if both `title` and `revision` parameters are present.
          type: string
          required: false
      responses:
        '200':
          description: MediaWiki Wikitext.
          schema:
            type: string
        '403':
          description: Access to the specific revision is restricted
          schema:
            $ref: '#/definitions/problem'
        '404':
          description: Unknown page title or revision
          schema:
            $ref: '#/definitions/problem'
        '409':
          description: Revision was restricted
          schema:
            $ref: '#/definitions/problem'
        '410':
          description: Page was deleted
          schema:
            $ref: '#/definitions/problem'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'

      x-route-filters:
        - type: default
          name: ratelimit_route
          options:
            limits:
              internal: 10
              external: 5

      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/parsoid/transform/html/to/wikitext{/title}{/revision}
              headers:
                if-match: '{{if-match}}'
              body:
                html: '{{html}}'
                scrub_wikitext: '{{scrub_wikitext}}'
      x-monitor: false

  /wikitext/to/html{/title}{/revision}:
    post:
      tags:
        - Transforms
      summary: Transform Wikitext to HTML
      description: |
        Transform wikitext to HTML. Note that if you set `stash: true`, you
        also need to supply the title.

        - Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable)
        - Rate limit: 5 req/s
      consumes:
        - multipart/form-data
      produces:
        - text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/1.6.0"
      parameters:
        - name: title
          in: path
          description: "Page title. Use underscores instead of spaces. Example: `Main_Page`."
          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
          x-textarea: true
        - name: body_only
          in: formData
          description: Return only `body.innerHTML`
          type: boolean
          required: false
        - name: stash
          in: formData
          description: Whether to temporarily stash the result of the transformation
          type: boolean
          required: false
      responses:
        '200':
          description: See wikipage https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec
          schema:
            type: string
        '403':
          description: access to the specific revision is restricted
          schema:
            $ref: '#/definitions/problem'
        '404':
          description: Unknown page title or revision
          schema:
            $ref: '#/definitions/problem'
        '409':
          description: Revision was restricted
          schema:
            $ref: '#/definitions/problem'
        '410':
          description: Page was deleted
          schema:
            $ref: '#/definitions/problem'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'

      x-route-filters:
        - type: default
          name: ratelimit_route
          options:
            limits:
              internal: 10
              external: 5

      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/parsoid/transform/wikitext/to/html{/title}{/revision}
              body:
                wikitext: '{{wikitext}}'
                body_only: '{{body_only}}'
                stash: '{{stash}}'
      x-monitor: true
      x-amples:
        - title: Transform wikitext to html
          request:
            params:
              domain: en.wikipedia.org
              title: User:BSitzmann_(WMF)/MCS/Test/Frankenstein
            body:
              wikitext: == Heading ==
              body_only: true
          response:
            status: 200
            headers:
              content-type: /^text\/html.+/
            body: /^<h2.*> Heading <\/h2>$/

  /wikitext/to/lint{/title}{/revision}:
    post:
      tags:
        - Transforms
      summary: Check Wikitext for lint errors
      description: |
        Parse the supplied wikitext and check it for lint errors.

        - Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental)
        - Rate limit: 5 req/s
      consumes:
        - multipart/form-data
        - application/json
      produces:
        - application/json
      parameters:
        - name: title
          in: path
          description: "Page title. Use underscores instead of spaces. Example: `Main_Page`."
          type: string
          required: false
        - name: revision
          in: path
          description: The page revision
          type: integer
          required: false
        - name: wikitext
          in: formData
          description: The Wikitext to check
          type: string
          required: true
          x-textarea: true
      responses:
        '200':
          description: Linter errors, if any, as a JSON blob
          schema:
            type: object
        '404':
          description: Unknown page title
          schema:
            $ref: '#/definitions/problem'
        '409':
          description: Latest revision was restricted
          schema:
            $ref: '#/definitions/problem'
        '410':
          description: Page was deleted
          schema:
            $ref: '#/definitions/problem'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'

      x-route-filters:
        - type: default
          name: ratelimit_route
          options:
            limits:
              internal: 10
              external: 5

      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/parsoid/transform/wikitext/to/lint{/title}{/revision}
              body:
                wikitext: '{{wikitext}}'
      x-monitor: false

# Keeping this in, as we'll re-introduce a html2html end point later.
#  /html/to/html{/title}{/revision}:
#    post:
#      tags:
#        - Transforms
#
#      description: |
#        Update / refresh / sanitize HTML
#
#        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
#      consumes:
#        - multipart/form-data
#      produces:
#        - text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/1.6.0"
#      parameters:
#        - 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-textarea: true
#        - name: body_only
#          in: formData
#          description: Return only `body.innerHTML`
#          type: boolean
#          required: false
#      responses:
#        '200':
#          description: See wikipage https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec
#        '403':
#          description: access to the specific revision is restricted
#          schema:
#            $ref: '#/definitions/problem'
#        '404':
#          description: Unknown page title or revision
#          schema:
#            $ref: '#/definitions/problem'
#        '409':
#          description: Revision was restricted
#          schema:
#            $ref: '#/definitions/problem'
#        '410':
#          description: Page was deleted
#          schema:
#            $ref: '#/definitions/problem'
#        default:
#          description: Error
#          schema:
#            $ref: '#/definitions/problem'
#      x-request-handler:
#        - get_from_backend:
#            request:
#              uri: /{domain}/sys/parsoid/transform/html/to/html{/title}{/revision}
#              headers:
#                if-match: '{if-match}'
#              body:
#                html: '{html}'
#                body_only: '{body_only}'
#      x-monitor: false

  /section-changes/to/wikitext/{title}/{revision}:
    post:
      tags:
        - Transforms

      summary: Transform modified HTML sections to Wikitext.
      description: |
        This entry point provides efficient HTML section edit functionality.
        The client can send back only modified HTML sections, and retrieve the
        full Wikitext of the page.

        - Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
        - Rate limit: 5 req/s
      consumes:
        - application/json
      produces:
        - text/plain; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/wikitext/1.0.0"
      parameters:
        - name: title
          in: path
          description: "Page title. Use underscores instead of spaces. Example: `Main_Page`."
          type: string
          required: true
        - name: revision
          in: path
          description: The page revision
          type: integer
          required: true
        - in: body
          description: Section changes to transform
          required: true
          schema:
            type: object
            properties:
              changes:
                type: object
                patternProperties:
                  '^mw\w+$':
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        html:
                          type: string
                      additionalProperties: false
                example:
                  mwAg:
                    - html: '<h2>Prepended section</h2>'
                    - id: mwAg
                    - html: '<h2>Appended Section</h2>'
              scrub_wikitext:
                type: boolean
                description: Normalise the DOM to yield cleaner wikitext?
            required:
              - changes
        - name: if-match
          in: header
          description: |
            The `ETag` header of the original render indicating it's revision and timeuuid.
            Required if both `title` and `revision` parameters are present.
          type: string
          required: false
      responses:
        '200':
          description: Wikitext of the full page.
          schema:
            type: string
        '400':
          description: Illegal JSON provided or section id does not exist
          schema:
            $ref: '#/definitions/problem'
        '403':
          description: access to the specific revision is restricted
          schema:
            $ref: '#/definitions/problem'
        '404':
          description: Unknown page title or revision
          schema:
            $ref: '#/definitions/problem'
        '409':
          description: Revision was restricted
          schema:
            $ref: '#/definitions/problem'
        '410':
          description: Page was deleted
          schema:
            $ref: '#/definitions/problem'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'

      x-route-filters:
        - type: default
          name: ratelimit_route
          options:
            limits:
              internal: 10
              external: 5

      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/parsoid/transform/changes/to/wikitext/{title}/{revision}
              headers:
                if-match: '{{if-match}}'
              body:
                changes: '{{changes}}'
                scrub_wikitext: '{{scrub_wikitext}}'
      x-monitor: false