swagger.yaml

openapi: 3.0.3
info:
  title: Balchivist API
  description: |-
    Balchivist is a web application that allows you to easily search for current and historical datasets published by the Wikimedia Foundation. The Balchivist API allows you to interact with the Balchivist database programmatically, allowing you to quickly find and download datasets.

    You can also browse Balchivist [using the web interface](https://dumps.wmcloud.org) or view the [source code behind Balchivist](https://github.com/balchivist).
  version: 2.0.0
  license:
    name: GNU General Public License v3.0
    url: https://www.gnu.org/licenses/gpl-3.0.en.html
  contact:
    name: Contact the developer
    url: https://meta.wikimedia.org/wiki/User_talk:Hydriz
servers:
  - url: https://dumps.wmcloud.org
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
  - {}
tags:
  - name: Users
  - name: Family/Dataset/Snapshot
  - name: Nodes
paths:
  /api/v1/users/:
    get:
      tags:
        - Users
      summary: Get all users
      description: Get a list of all users known to Balchivist.
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/users/{user_id}/:
    get:
      tags:
        - Users
      summary: Get a specific user
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
  /api/v1/users/{user_id}/watchlists/:
    get:
      tags:
        - Users
      summary: Get all watchlists of a specific user
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
      parameters:
        - name: user_id
          in: path
          description: User ID
          required: true
          schema:
            type: string
  /api/v1/families:
    get:
      tags:
        - Family/Dataset/Snapshot
      summary: Get all families
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}:
    get:
      tags:
        - Family/Dataset/Snapshot
      summary: Get a specific family
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/:
    post:
      tags:
        - Family/Dataset/Snapshot
      summary: Create new family
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                identifier: wikibase
                url: https://dumps.wikimedia.org/other/wikibase/
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}/:
    patch:
      tags:
        - Family/Dataset/Snapshot
      summary: Edit a specific family
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                identifier: dumps
                url: https://dumps.wikimedia.org/backup-index.html
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}/datasets:
    get:
      tags:
        - Family/Dataset/Snapshot
      summary: Get all datasets in a family
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}/datasets/{dataset_id}:
    get:
      tags:
        - Family/Dataset/Snapshot
      summary: Get a specific dataset in a family
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
        - name: dataset_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}/datasets/:
    post:
      tags:
        - Family/Dataset/Snapshot
      summary: Create new dataset in a family
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                identifier: dewiki
                url: https://dumps.wikimedia.org/dewiki/
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}/datasets/{dataset_id}/:
    patch:
      tags:
        - Family/Dataset/Snapshot
      summary: Edit a specific dataset in a family
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                identifier: enwiki
                url: https://dumps.wikimedia.org/enwiki/
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
        - name: dataset_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}/datasets/{dataset_id}/snapshots:
    get:
      tags:
        - Family/Dataset/Snapshot
      summary: Get all snapshots in a dataset in a family
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
        - name: dataset_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}/datasets/{dataset_id}/snapshots/{snapshot_id}:
    get:
      tags:
        - Family/Dataset/Snapshot
      summary: Get a specific snapshot in a dataset in a family
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
        - name: dataset_id
          in: path
          schema:
            type: string
          required: true
        - name: snapshot_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}/datasets/{dataset_id}/snapshots/:
    post:
      tags:
        - Family/Dataset/Snapshot
      summary: Create new snapshot in a dataset in a family
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                identifier: "20220601"
                date: "2022-06-01"
                url: https://dumps.wikimedia.org/enwiki/20220601/
                status: done
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
        - name: dataset_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/families/{family_id}/datasets/{dataset_id}/snapshots/{snapshot_id}/:
    patch:
      tags:
        - Family/Dataset/Snapshot
      summary: Edit a specific snapshot in a dataset in a family
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                identifier: "20220601"
                date: "2022-06-01"
                url: https://dumps.wikimedia.org/enwiki/20220601/
                status: done
                files:
                  enwiki-20220601-stub-meta-history.xml.gz:
                    size: 77871777685
                    url: /enwiki/20220601/enwiki-20220601-stub-meta-history.xml.gz
                    md5: 7355987913ea7a7c058d204c7fc36b06
                    sha1: 5d7d5efb71c71a3bca94b04e79e0677657cbe24c
                  enwiki-20220601-stub-meta-current.xml.gz:
                    size: 5625484451
                    url: /enwiki/20220601/enwiki-20220601-stub-meta-current.xml.gz
                    md5: 0579744b2f2ebd77a6e1f307053cdc06
                    sha1: 20d58743f0b2de29f1ee295b3d974989112c72cc
                  enwiki-20220601-stub-articles.xml.gz:
                    size: 2339125147
                    url: /enwiki/20220601/enwiki-20220601-stub-articles.xml.gz
                    md5: 562556227d202909db81096092954249
                    sha1: 7fe80134673430a54c0bce6e828546cc0a8c3224
      parameters:
        - name: family_id
          in: path
          schema:
            type: string
          required: true
        - name: dataset_id
          in: path
          schema:
            type: string
          required: true
        - name: snapshot_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/nodes:
    get:
      tags:
        - Nodes
      summary: Get all nodes
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/nodes/{node_id}:
    get:
      tags:
        - Nodes
      summary: Get a specific node
      parameters:
        - name: node_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/nodes/:
    post:
      tags:
        - Nodes
      summary: Create new node
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {}
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/nodes/{node_id}/configs:
    get:
      tags:
        - Nodes
      summary: Get all configs for a node
      parameters:
        - name: node_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/nodes/{node_id}/configs/{config_key}:
    get:
      tags:
        - Nodes
      summary: Get a specific config for a node
      parameters:
        - name: node_id
          in: path
          schema:
            type: string
          required: true
        - name: config_key
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/nodes/{node_id}/configs/:
    post:
      tags:
        - Nodes
      summary: Create new config for a specific node
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {}
      parameters:
        - name: node_id
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /api/v1/converter:
    get:
      tags:
        - General
      summary: Convert to local language
      parameters:
        - name: language
          in: query
          schema:
            type: string
          example: en
        - name: db
          in: query
          schema:
            type: string
          example: enwiki
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}