spec.yaml

openapi: 3.0.0
info:
  version: 1.1.0
  title: Citoid
  description: A citation service relying on Zotero
  termsOfService: https://wikimediafoundation.org/wiki/Terms_of_Use
  contact:
    name: the Wikimedia Services team
    url: http://mediawiki.org/wiki/Services
  license:
    name: Apache2
    url: http://www.apache.org/licenses/LICENSE-2.0
paths:
  # from routes/root.js
  /robots.txt:
    get:
      tags:
        - Root
        - Robots
      description: Gets robots.txt
      responses:
        200:
          description: Success
  /:
    get:
      tags:
        - Root
      description: The root service end-point
      responses:
        200:
          description: Success
      x-amples:
        - title: spec from root
          request:
            query:
              spec: true
          response:
            status: 200
  # from routes/info.js
  /_info:
    get:
      tags:
        - Service information
      description: Gets information about the service
      responses:
        "200":
          description: OK
      x-amples:
        - title: retrieve service info
          request: {}
          response:
            status: 200
            headers:
              content-type: application/json
            body:
              name: /.+/
              description: /.+/
              version: /.+/
              home: /.+/
  # from routes/citoid.js
  /api:
    get:
      tags:
        - Citations (Query strings) (deprecated)
      description: Converts URLs, DOIs, ISBNs, PMIDs, etc into citations
      parameters:
        - name: format
          in: query
          description: The format to use for the resulting citation data
          schema:
            type: string
            enum:
              - mediawiki
              - mediawiki-basefields
              - zotero
              - bibtex
              - wikibase
          required: true
        - name: search
          in: query
          description: >
            URL of an article, DOI, ISBN, PMCID or PMID in the URL-encoded format.
            Note that on the Swagger-UI doc page you don't need to URI-encode the
            parameter manually, it will be done by the docs engine.
          schema:
            type: string
          required: true
        - name: Accept-Language
          in: header
          schema:
            type: string
          required: false
          description: >
            Provides citation metadata in the requested language, if it is available.
      x-amples:
        - title: bad URL
          request:
            query:
              format: mediawiki
              search: https://en.wikipedia.org/404
            headers:
              accept-language: en
          response:
            status: 404
        - title: Zotero and citoid alive
          request:
            query:
              format: mediawiki
              search: https://en.wikipedia.org/wiki/Darth_Vader
          response:
            status: 200
            headers:
              content-type: /^application\/json/
            body:
              - title: Darth Vader
                language: en
                itemType: encyclopediaArticle
                encyclopediaTitle: Wikipedia
      responses:
        "200":
          description: The citation data in the requested format
          content:
            application/json; charset=utf-8;:
              schema:
                $ref: "#/components/schemas/result"
            application/x-bibtex; charset=utf-8:
              schema:
                $ref: "#/components/schemas/result"
        "404":
          description: Citation data was not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/problem"
        "415":
          description: Could not get citation data from unsupported media type
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/problem"
  # from routes/citoid.js
  /{format}/{query}:
    get:
      tags:
        - Citations (Restbase shim)
      summary: Get citation data given an article identifier.
      description: |
        Generates citation data given a URL, DOI, ISBN, PMID, or PMCID.

        Automated requests can be made at a rate of 1 request per second (rps).

        See more at [Citoid service documentation](https://www.mediawiki.org/wiki/Citoid)

        The citation data can be requested in one of the following formats:
          - `mediawiki`: format designed for MediaWiki to be used with `templateData`.
            Uses [Zotero field names](https://aurimasv.github.io/z2csl/typeMap.xml).
          - `mediawiki-basefields`: `mediawiki` format with Zotero `basefield` field names.
          - `zotero`: format used by [Zotero](https://www.zotero.org/).
          - `bibtex`: format used in conjunction with LaTeX documents.
            See [bibtex.org](http://www.bibtex.org/).
          - `wikibase`: format designed for [Wikibase](https://www.mediawiki.org/wiki/Extension:Wikibase_Repository).

        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
      parameters:
        - name: format
          in: path
          description: The format to use for the resulting citation data
          schema:
            type: string
            enum:
              - mediawiki
              - mediawiki-basefields
              - zotero
              - bibtex
              - wikibase
          required: true
        - name: query
          in: path
          description: |
            URL of an article, DOI, PMCID or PMID in the URL-encoded format.
            Note that on the Swagger-UI doc page you don't need to URI-encode the param manually,
            it will be done by the docs engine.
          required: true
          schema:
            type: string
        - name: Accept-Language
          in: header
          description: |
            For some articles the result depends on the `Accept-Language` header,
            so provide it if localized content is required.
          schema:
            type: string
      responses:
        200:
          description: The citation data in the requested format
          content:
            application/json; charset=utf-8;:
              schema:
                $ref: "#/components/schemas/result"
            application/x-bibtex; charset=utf-8:
              schema:
                $ref: "#/components/schemas/result"
        404:
          description: Citation data was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/problem"
      operationId: getCitation
components:
  schemas:
    result:
      required:
        - title
        - url
        - itemType
      type: object
      properties:
        itemType:
          type: string
        title:
          type: string
        url:
          type: string
    problem:
      required:
        - type
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        detail:
          type: string
        instance:
          type: string