content.yaml

openapi: 3.0.1
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: Apache licence, v2
    url: https://www.apache.org/licenses/LICENSE-2.0
tags:
  - name: Page content
    description: page content in different formats
paths:
  /:
    get:
      tags:
        - Page content
      summary: List page-related API entry points.
      description: |
        Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable)
      responses:
        200:
          description: A list of page-related API end points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listing'
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
      x-monitor: false

  /title/{title}:
    get: &title_title_get_spec
      tags:
        - Page content
      summary: Get revision metadata for a title.
      description: |
        Returns the revision metadata for the given title. If a revision ID is provided,
        metadata for that revision is returned, otherwise the latest revision ID is assumed.

        Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable).
      parameters:
        - name: title
          in: path
          description: 'Page title. Use underscores instead of spaces. Use percent-encoding. Example: `Main_Page`.'
          required: true
          schema:
            type: string
      responses:
        200:
          description: The latest revision metadata for the provided title.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/revision'
        301:
          description: |
            A permanent redirect is returned if the supplied article title was not in the normalized form.
            To avoid these redirects, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform
            title normalization client side.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        302:
          description: |
            The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects).
            The `location` header points to the redirect target.
            If you would like to avoid automatically following redirect pages, set the `redirect=false` query parameter.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        404:
          description: Unknown page title or no revisions found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/page_revisions/page/{title}
              headers:
                # FIXME: Temporary work-around (see T120212).
                cache-control: 'no-cache'
                if-unmodified-since: '{{if-unmodified-since}}'
      x-monitor: true
      x-amples:
        - title: Get rev by title from storage
          request:
            params:
              domain: en.wikipedia.org
              title: User:BSitzmann_(WMF)/MCS/Test/Frankenstein
          response:
            status: 200
            headers:
              etag: /.+/
              content-type: application/json
            body:
              items:
                - title: 'User:BSitzmann_(WMF)/MCS/Test/Frankenstein'
                  rev: /\d+/
                  tid: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
                  comment: /.*/
                  page_language: 'en'

  /title/{title}/{revision}:
    get:
      <<: *title_title_get_spec
      parameters:
        - name: title
          in: path
          description: 'Page title. Use underscores instead of spaces. Use percent-encoding. Example: `Main_Page`.'
          required: true
          schema:
            type: string
        - name: revision
          in: path
          description: The revision id
          required: true
          schema:
            type: integer
      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/page_revisions/page/{title}/{revision}
              headers:
                # FIXME: Temporary work-around (see T120212).
                cache-control: 'no-cache'
                if-unmodified-since: '{{if-unmodified-since}}'
      x-monitor: false

  /html/{title}:
    x-route-filters:
      - path: ./lib/access_check_filter.js
        options:
          redirect_cache_control: '{{options.response_cache_control}}'
          attach_body_to_redirect: true
      - path: lib/security_response_header_filter.js
        options:
          allowInlineStyles: true
      - path: lib/content_negotiation_filter.js
    get:
      x-route-filters:
        - path: lib/ensure_content_type.js
        - path: ./lib/language_variants_filter.js
      tags:
        - Page content
      summary: Get latest HTML for a title.
      description: |
        Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable)
      parameters:
        - name: title
          in: path
          description: 'Page title. Use underscores instead of spaces. Use percent-encoding. Example: `Main_Page`.'
          required: true
          schema:
            type: string
        - name: redirect
          in: query
          description: |
            Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body.
            To get a 200 response instead, supply `false` to the `redirect` parameter.
          schema:
            type: boolean
          required: false
        - name: stash
          in: query
          description: |
            Whether to temporary stash data-parsoid in order to support transforming the
            modified content later. If this parameter is set, requests are rate-limited on
            a per-client basis (max 5 requests per second per client)
          schema:
            type: boolean
        - name: Accept-Language
          in: header
          description: |
            The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language.
          schema:
            type: string
      responses:
        200:
          description: |
            The latest HTML for the given page title.

            See [the MediaWiki DOM
            spec](https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec) for a
            description of the MediaWiki-specific semantic markup in this HTML.
            Note that additional metadata is available in the HTML head.
          headers:
            ETag:
              description: |
                ETag header indicating the revision and render timeuuid
                separated by a slash:
                "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc"
                This ETag can be passed to the HTML save end point (as
                `base_etag` POST parameter), and can also be used to retrieve
                the exact corresponding data-parsoid metadata, by requesting
                the specific `revision` and `tid` indicated by the `ETag`.
              schema:
                type: string
          content:
            text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/2.1.0":
              schema:
                type: string

            application/json:
              schema:
                type: object
        301:
          description: |
            A permanent redirect is returned if the supplied article title was not in the normalized form.
            To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform
            title normalization client-side.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        302:
          description: |
            The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects).
            The `location` header points to the redirect target, and the body contains the actual page contents as HTML.
            If you would like to avoid automatically following redirect pages, set the `redirect=false` query parameter.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        404:
          description: Unknown page title
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
      x-request-handler:
        - get_from_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}
              headers:
                cache-control: '{{cache-control}}'
                if-unmodified-since: '{{if-unmodified-since}}'
                x-restbase-mode: '{{x-restbase-mode}}'
                x-restbase-parentrevision: '{{x-restbase-parentrevision}}'
              query:
                stash: '{{stash}}'
      x-monitor: true
      x-amples:
        # FIXME: This depends on our 'no change' detection optimization to
        # avoid filling up storage with re-renders. We have plenty of data on
        # Parsoid backend requests, so there shouldn't be a need to test this
        # per-instance.
        #- title: Get html by title from Parsoid
        #  request:
        #    params:
        #      title: Foobar
        #    headers:
        #      cache-control: no-cache
        #  response:
        #    status: 200
        #    headers:
        #      etag: /.+/
        #      content-type: /^text\/html.+/
        #    body: /^<!DOCTYPE html>.*/
        - title: Get html by title from storage
          request:
            params:
              domain: en.wikipedia.org
              title: User:BSitzmann_(WMF)/MCS/Test/Frankenstein
          response:
            status: 200
            headers:
              etag: /.+/
              content-type: /^text\/html.+/
            body: /^<!DOCTYPE html>.*/

  /html/{title}/{revision}:
    get: &html_title_revision_get_spec
      tags:
        - Page content
      summary: Get HTML for a specific title/revision & optionally timeuuid.
      description: |
        Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable)
      operationId: getFormatRevision
      parameters:
        - name: title
          in: path
          description: 'Page title. Use underscores instead of spaces. Use percent-encoding. Example: `Main_Page`.'
          required: true
          schema:
            type: string
        - name: revision
          in: path
          description: The revision
          required: true
          schema:
            type: integer
        - name: redirect
          in: query
          description: |
            Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body.
            To get a 200 response instead, supply `false` to the `redirect` parameter.
          schema:
            type: boolean
        - name: stash
          in: query
          description: |
            Whether to temporary stash data-parsoid in order to support transforming the
            modified content later. If this parameter is set, requests are rate-limited on
            a per-client basis (max 5 requests per second per client)
          schema:
            type: boolean
        - name: Accept-Language
          in: header
          description: |
            The desired language variant code for wikis where LanguageConverter is enabled. Example: `sr-el` for Latin transcription of the Serbian language.
          schema:
            type: string
      responses:
        200:
          description: |
            The html for the given page, revision and tid.

            See [the MediaWiki DOM
            spec](https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec) for a
            description of the MediaWiki-specific semantic markup in this HTML.
            Note that additional metadata is available in the HTML head.

            This HTML can be edited using arbitrary HTML tools. The modified HTML
            can be converted back to wikitext using the
            [/transform/html/to/wikitext{/title}{/revision}](#!/Transforms/transform_html_to_wikitext__title___revision__post)
            entry point.
          headers:
            ETag:
              description: |
                ETag header indicating the revision and render timeuuid
                separated by a slash:
                "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc"
                This ETag can be passed to the HTML save end point (as
                `base_etag` POST parameter), and can also be used to retrieve
                the exact corresponding data-parsoid metadata, by requesting
                the specific `revision` and `tid` indicated by the `ETag`.
              schema:
                type: string
          content:
            text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/2.1.0":
              schema:
                type: string
            application/json:
              schema:
                type: object
        301:
          description: |
            A permanent redirect is returned if the supplied article title was not in the normalized form.
            To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform
            title normalization client-side.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        302:
          description: |
            The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects).
            The `location` header points to the redirect target, and the body contains the actual page revision contents as HTML.
            If you would like to avoid automatically following redirect pages, set the `redirect=false` query parameter.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        400:
          description: Invalid revision or tid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        403:
          description: Access to the specific revision is restricted
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        404:
          description: Unknown page, revision or tid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/parsoid/html/{title}/{revision}
              headers:
                cache-control: '{{cache-control}}'
                if-unmodified-since: '{{if-unmodified-since}}'
                x-restbase-mode: '{{x-restbase-mode}}'
                x-restbase-parentrevision: '{{x-restbase-parentrevision}}'
              query:
                stash: '{{stash}}'
      x-monitor: false

  /data-parsoid/{title}/{revision}/{tid}:
    x-route-filters:
      - path: ./lib/access_check_filter.js
        options:
          redirect_cache_control: '{{options.response_cache_control}}'
          attach_body_to_redirect: true
    get:
      tags:
        - Page content
      summary: Get data-parsoid metadata for a specific title/revision/tid.
      description: |
        Data-parsoid is metadata used by
        [Parsoid](https://www.mediawiki.org/wiki/Parsoid) to support clean
        round-tripping conversions between HTML and Wikitext. Among other
        things, it contains the original Wikitext offsets of each HTML
        element, keyed by element ID. The format is unstable.

        The metadata in data-parsoid is specific to a specific HTML render.
        For this reason, you need to supply the exact `revision` and `tid` as
        provided in the `ETag` header of the HTML response.

        Stability: [Stable](https://www.mediawiki.org/wiki/API_versioning#Stable)
      parameters:
        - name: title
          in: path
          description: 'Page title. Use underscores instead of spaces. Use percent-encoding. Example: `Main_Page`.'
          required: true
          schema:
            type: string
        - name: revision
          in: path
          description: The revision
          required: true
          schema:
            type: integer
        - name: tid
          in: path
          description: The revision's time ID
          required: true
          schema:
            type: string
        - name: redirect
          in: query
          description: |
            Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body.
            To get a 200 response instead, supply `false` to the `redirect` parameter.
          schema:
            type: boolean
      responses:
        200:
          description: The latest Parsoid data for the given page
          headers:
            ETag:
              description: 'Revision / tid: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc"'
              schema:
                type: string
          content:
            application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/data-parsoid/2.1.0:
              schema:
                $ref: '#/components/schemas/data-parsoid'
        301:
          description: |
            A permanent redirect is returned if the supplied article title was not in the normalized form.
            To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform
            title normalization client-side.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        302:
          description: |
            The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects).
            The `location` header points to the redirect target, and the body contains the actual data-parsoid for the redirect page.
            If you would like to avoid automatically following redirect pages, set the `redirect=false` query parameter.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        400:
          description: Invalid revision
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        403:
          description: Access to the specific revision is restricted
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        404:
          description: Unknown page, revision or tid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/parsoid/data-parsoid/{title}/{revision}/{tid}
              headers:
                cache-control: '{{cache-control}}'
                if-unmodified-since: '{{if-unmodified-since}}'
                x-restbase-mode: '{{x-restbase-mode}}'
                x-restbase-parentrevision: '{{x-restbase-parentrevision}}'
      x-monitor: false

  /lint/{title}:
    x-route-filters:
      - path: ./lib/access_check_filter.js
        options:
          redirect_cache_control: '{{options.response_cache_control}}'
      - path: lib/security_response_header_filter.js
    get: &lint_title_get_spec
      tags:
        - Page content
      summary: Get the linter errors for a specific title/revision.
      description: |
        Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental)
      parameters:
        - name: title
          in: path
          description: 'Page title. Use underscores instead of spaces. Use percent-encoding. Example: `Main_Page`.'
          required: true
          schema:
            type: string
      responses:
        200:
          description: |
            The lint errors for the given page and optionally revision.

            See [the Linter extension docs](https://www.mediawiki.org/wiki/Extension:Linter) for more
            details.
          content:
            application/json:
              schema:
                type: object
        301:
          description: |
            A permanent redirect is returned if the supplied article title was not in the normalized form.
            To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform
            title normalization client-side.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        302:
          description: |
            The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects).
            The `location` header points to the redirect target, and the body contains the actual page revision contents as HTML.
            If you would like to avoid automatically following redirect pages, set the `redirect=false` query parameter.

            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
        400:
          description: Invalid revision or tid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        403:
          description: Access to the specific revision is restricted
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        404:
          description: Unknown page, revision or tid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/parsoid/lint/{title}
      x-monitor: false

  /lint/{title}/{revision}:
    get:
      <<: *lint_title_get_spec
      parameters:
        - name: title
          in: path
          description: 'Page title. Use underscores instead of spaces. Use percent-encoding. Example: `Main_Page`.'
          required: true
          schema:
            type: string
        - name: revision
          in: path
          description: The revision
          required: true
          schema:
            type: integer
      x-request-handler:
        - get_from_backend:
            request:
              uri: /{domain}/sys/parsoid/lint/{title}/{revision}

components:
  schemas:
    revisions:
      description: The result format for revision listing
      required:
        - items
      type: object
      properties:
        items:
          $ref: '#/components/schemas/revisionIdentifier'

    listing:
      description: The result format for listings
      required:
        - items
      type: object
      properties:
        items:
          type: array
          items:
            type: string
        _links:
          type: object
          properties:
            next:
              type: object
              properties:
                href:
                  type: string
                  description: Relative link to next result page.

    data-parsoid:
      description: Result format for Parsoid data queries
      required:
        - counter
        - ids
      type: object
      properties:
        counter:
          type: integer
          format: int32
        ids:
          type: object
          properties: {}

    revision:
      description: Result format for revision items
      required:
        - count
        - items
      type: object
      properties:
        count:
          type: integer
          format: int32
        items:
          $ref: '#/components/schemas/revisionInfo'

    revisionInfo:
      type: object
      description: Complete information about the revision
      properties:
        title:
          type: string
        page_id:
          type: integer
          format: int32
        rev:
          type: integer
          format: int32
        tid:
          type: string
        comment:
          type: string
        restrictions:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        user_id:
          type: integer
          format: int32
        user_text:
          type: string
        timestamp:
          type: string
          format: date-time
        redirect:
          type: boolean
        page_language:
          type: string

    revisionIdentifier:
      type: object
      description: Unique revision identifier
      properties:
        revision:
          type: integer
          format: int32
        tid:
          type: string