swagger: '2.0'
info:
  version: '1.0.0-beta'
  title: MediaWiki PDF API
  description: Page PDF Render 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
paths:
  /pdf/{title}:
    x-route-filters:
      - path: ./lib/revision_table_access_check_filter.js
        options:
          redirect_cache_control: '{{options.cache_control}}'
    get:
      tags:
        - Page content
      summary: Get a page as PDF
      description: |
        Renders the page content as PDF.

        Stability: [experimental](https://www.mediawiki.org/wiki/API_versioning#Experimental)
      produces:
        - application/pdf
      parameters:
        - name: title
          in: path
          description: "Page title. Use underscores instead of spaces. Example: `Main_Page`."
          type: string
          required: true
      responses:
        '200':
          description: The PDF render of an article
          schema:
            type: file
          headers:
            ETag:
              description: >
                Syntax: "{revision}/{tid}".
                Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc"
        '404':
          description: Unknown page title
          schema:
            $ref: '#/definitions/problem'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'

      x-request-handler:
        - get_latest_revision:
            request:
              method: get
              uri: /{domain}/sys/page_revisions/page/{title}
        - get_pdf_from_backend:
            request:
              method: get
              # Note: The title needs to be encoded twice.
              uri: '{{options.uri}}/pdf?accessKey={options.secret}&url={{default(options.scheme, "https")}}://{{domain}}/wiki/{_encodeURIComponent(title)}%3Fprintable=yes'
            return:
              status: 200
              headers:
                # Firefox supports filename*= syntax while Chrome respect
                # filename=. Safari is stupid and understands neither.
                # TODO: Quote raw `"` chars in filename.
                content-disposition: 'attachment; {{filenameParameters(request.params.title)}}'
                content-type: '{{get_pdf_from_backend.headers.content-type}}'
                content-length: '{{get_pdf_from_backend.headers.content-length}}'
                cache-control: '{{default(options.cache_control, "s-maxage=600, max-age=600")}}'
                etag: '{{get_latest_revision.headers.etag}}'
              body: '{{get_pdf_from_backend.body}}'
      x-monitor: false # PDF generation is expensive and it's not stored, so don't run checker script