paths:
  /graph/png/{title}/{revision}/{graph_id}:
    get:
      tags:
        - Page content
      summary: Get PNG graph images referenced in page revisions.
      description: |
        Retrieve PNG graph images embedded in specific revisions of a
        page. See [the Graphoid
        documentation](https://www.mediawiki.org/wiki/Extension:Graph#Graphoid_service)
        for details.

        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
      produces:
        - image/png
      parameters:
        - name: title
          in: path
          description: The page title
          type: string
          required: true
        - name: revision
          in: path
          description: The page revision, or 0 for the latest
          type: integer
          required: true
        - name: graph_id
          in: path
          description: The graph ID, consisting of a hash and the suffix `.png`.
          type: string
          required: true
      responses:
        '200':
          description: The PNG render of the requested graph.
          schema:
            type: blob
          # FIXME: Actually return a decent ETag from graphoid & document it here!
          # See https://phabricator.wikimedia.org/T125924
          #headers:
          #  ETag:
          #    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'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'

      x-request-handler:
        - get_from_graphoid:
            request:
              uri: '{+ $$.options.host }/{domain}/v1/png/{title}/{revision}/{graph_id}'

      x-monitor: true
      x-amples:
        - title: Get a graph from Graphoid
          request:
            params:
              domain: en.wikipedia.org
              title: User:Pchelolo/Graph
              revision: 0
              graph_id: c1c5d432407bd5fd7435f5edfb6fdb73ffd4bc9e.png
          response:
            status: 200
            headers:
              content-type: image/png