# Mathoid - math formula rendering service
tags:
  - name: Math
    description: formula rendering
paths:
  /math/check/{type}:
    post:
      tags: ['Math']
      summary: Check and normalize a TeX formula.
      description: |
        Checks the supplied TeX formula for correctness and returns the
        normalised formula representation as well as information about
        identifiers. Available types are tex and inline-tex. The response
        contains the `x-resource-location` header which can be used to retrieve
        the render of the checked formula in one of the supported rendering
        formats. Just append the value of the header to `/media/math/{format}/`
        and perform a GET request against that URL.

        Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable).
      produces:
        - application/json
      parameters:
        - name: type
          in: path
          description: The input type of the given formula; can be tex or inline-tex
          type: string
          required: true
          enum:
            - tex
            - inline-tex
            - chem
        - name: q
          in: formData
          description: The formula to check
          type: string
          required: true
      responses:
        '200':
          description: Information about the checked formula
        '400':
          description: Invalid type
          schema:
            $ref: '#/definitions/problem'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'
      x-monitor: true
      x-amples:
        - title: Mathoid - check test formula
          request:
            params:
              domain: wikimedia.org
              type: tex
            body:
              q: E=mc^{2}
          response:
            status: 200
            headers:
              content-type: /^application\/json/
              x-resource-location: /.+/
              cache-control: 'no-cache'
            body:
              success: true
              checked: /.+/
      x-request-handler:
        - get_from_sys:
            request:
              method: post
              uri: /wikimedia.org/sys/mathoid/check/{type}
              headers: '{{ request.headers }}'
              body: '{{ request.body }}'

  /math/formula/{hash}:
    get:
      tags: ['Math']
      summary: Get a previously-stored formula
      description: |
        Returns the previously-stored formula via `/media/math/check/{type}` for
        the given hash.

        Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable).
      produces:
        - application/json
      parameters:
        - name: hash
          in: path
          description: The hash string of the previous POST data
          type: string
          required: true
          minLength: 1
      responses:
        '200':
          description: Information about the checked formula
        '404':
          description: Data for the given hash cannot be found
          schema:
            $ref: '#/definitions/problem'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'
      x-monitor: false
      x-request-handler:
        - get_from_sys:
            request:
              method: get
              uri: /wikimedia.org/sys/mathoid/formula/{hash}
              headers: '{{ request.headers }}'

  /math/render/{format}/{hash}:
    get:
      tags: ['Math']
      summary: Get rendered formula in the given format.
      description: |
        Given a request hash, renders a TeX formula into its mathematic
        representation in the given format. When a request is issued to the
        `/media/math/check/{format}` POST endpoint, the response contains the
        `x-resource-location` header denoting the hash ID of the POST data. Once
        obtained, this endpoint has to be used to obtain the actual render.

        Stability: [stable](https://www.mediawiki.org/wiki/API_versioning#Stable).
      produces:
        - image/svg+xml
        - application/mathml+xml
        - image/png
      parameters:
        - name: format
          in: path
          description: The output format; can be svg or mml
          type: string
          required: true
          enum:
            - svg
            - mml
            - png
        - name: hash
          in: path
          description: The hash string of the previous POST data
          type: string
          required: true
          minLength: 1
      responses:
        '200':
          description: The rendered formula
        '404':
          description: Unknown format or hash ID
          schema:
            $ref: '#/definitions/problem'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'
      x-monitor: false
      x-setup-handler:
        - init_svg:
            uri: /wikimedia.org/sys/key_value/mathoid_ng.svg
            body:
              keyType: string
              valueType: string
        - init_mml:
            uri: /wikimedia.org/sys/key_value/mathoid_ng.mml
            body:
              keyType: string
              valueType: string
        - init_png:
            uri: /wikimedia.org/sys/key_value/mathoid_ng.png
            body:
              keyType: string
              valueType: blob
      x-request-handler:
        - check_storage:
            request:
              method: get
              uri: /wikimedia.org/sys/key_value/mathoid_ng.{$.request.params.format}/{$.request.params.hash}
              headers:
                cache-control: '{{ cache-control }}'
            catch:
              status: 404
            return_if:
              status: '2xx'
            return:
              status: 200
              headers: "{{ merge({ 'cache-control': options.cache-control }, check_storage.headers) }}"
              body: '{{ check_storage.body }}'
        - postdata:
            request:
              uri: /wikimedia.org/sys/mathoid/formula/{request.params.hash}
        - mathoid:
            request:
              method: post
              uri: /wikimedia.org/sys/mathoid/render/{request.params.format}
              headers:
                content-type: application/json
                x-resource-location: '{{ request.params.hash }}'
              body: '{{postdata.body}}'