api/yaml/openapi.yaml

# THIS IS PULLED FROM SCRIPTS AND AUTOGENERATED!
# Please use openapi/combine.py to regenerate!
openapi: 3.0.0
info:
  version: 1.0.0
  description: This is the API specifications for interacting with the Warble Server.
  title: Apache Warble API
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
components:
  schemas:
    APIKeyResult:
      properties:
        encrypted:
          description: Whether the API Key is encrypted (in case of nodes/agents requesting
            it)
          example: false
          type: boolean
        key:
          description: The (encrypted?) API Key assigned by the server
          example: abcdef-1234
          type: string
      required:
      - encrypted
      - key
    ActionCompleted:
      properties:
        message:
          description: Acknowledgement message
          example: Action completed
          type: string
      required:
      - message
    Empty:
      properties:
        id:
          description: optional object ID
          type: string
        page:
          description: optional page id
          type: string
      required: []
    Error:
      properties:
        code:
          description: HTTP Error Code
          example: 403
          format: int16
          type: integer
        reason:
          description: Human readable error message
          example: You need to be logged in to view this endpoint!
          type: string
      required:
      - code
      - reason
    NodeCredentials:
      properties:
        hostname:
          description: The node's own perceived hostname
          example: foo1.warble.xyz
          type: string
        pubkey:
          description: The node's self-generated public RSA key, PEM-encoded
          type: string
        version:
          description: The version of Warble the node is running
          example: 0.1.0
          type: string
      required:
      - hostname
      - pubkey
      - version
    NodeDetails:
      properties:
        description:
          description: A description of the node
          example: This is the internal node in DC1
          type: string
        enabled:
          description: Whether the node is enabled or paused
          example: true
          type: boolean
        hostname:
          description: The node's own perceived hostname
          example: foo1.warble.xyz
          type: string
        id:
          description: the numeric ID of the node to modify
          example: 42
          type: integer
        ip:
          description: The IP generally associated with this client
          type: string
        lastping:
          description: The last UNIX timestamp of activity from the client
          type: integer
        location:
          description: Physical location of the node
          example: DC1, Chicago, Illinois
          type: string
        pubkey:
          description: The node's self-generated public RSA key, PEM-encoded
          type: string
        verified:
          description: Whether the node is verified as ours or not
          example: true
          type: boolean
        version:
          description: The version of Warble the node is running
          example: 0.1.0
          type: string
      required:
      - id
    Timeseries:
      properties:
        interval:
          type: string
        okay:
          type: boolean
        timeseries:
          items:
            $ref: '#/components/schemas/TimeseriesObject'
          type: array
    TimeseriesObject:
      properties:
        $item:
          description: A timeseries object
          example: 50
          type: integer
        $otheritem:
          description: A timeseries object
          example: 26
          type: integer
        date:
          description: Seconds since UNIX epoch
          example: 1508273
          type: integer
      required:
      - date
    UserAccount:
      properties:
        displayname:
          description: A display name (e.g. full name) for the account
          example: Warble User
          type: string
        email:
          description: Desired username (email address)
          example: guest@warble.xyz
          type: string
        password:
          description: Desired password for the account
          example: warbledemo
          type: string
      required:
      - email
      - password
      - displayname
    UserCredentials:
      properties:
        password:
          description: User password
          example: warbledemo
          type: string
        username:
          description: Username (email?)
          example: admin
          type: string
      required:
      - username
      - password
    WidgetApp:
      properties:
        blocks:
          description: Size (width) in UI blocks of the app
          example: 4
          type: integer
        datatype:
          description: The top category of this data
          example: repo
          type: string
        name:
          description: The title of the widget app
          example: Widget Title
          type: string
        representation:
          description: The visual representation style of this widget
          example: donut
          type: string
        source:
          description: The API endpoint to get data from
          example: code-evolution
          type: string
        target:
          type: string
        text:
          description: Text to insert into the widget (if paragraph type widget)
          type: string
        type:
          description: The type of widget
          example: My Widget
          type: string
      required:
      - type
      - name
      - blocks
    WidgetDesign:
      properties:
        rows:
          items:
            $ref: '#/components/schemas/WidgetRow'
          type: array
        title:
          type: string
    WidgetRow:
      properties:
        children:
          items:
            $ref: '#/components/schemas/WidgetApp'
          type: array
        name:
          type: string
    defaultWidgetArgs:
      properties:
        author:
          description: Turns on author view for code results, as opposed to the default
            committer view
          type: boolean
        collapse:
          description: for some widgets, this collapses sources based on a regex
          type: string
        distinguish:
          description: Enables distinguishing different types of data objects, subject
            to the individual API endpoint
          example: false
          type: boolean
        email:
          description: filter sources based on an email (a person)
          type: string
        from:
          description: If specified, compile data from this timestamp onwards
          example: 1400000000
          type: integer
        interval:
          description: If fetching histograms, this specifies the interval to pack
            figures into. Can be day, week, month, quarter or year
          example: month
          type: string
        links:
          description: for relationship maps, this denotes the minimum link strength
            (no. of connections) that makes up a link.
          type: integer
        page:
          type: string
        quick:
          description: Turns on quick data for some endpoints, returning only sparse
            data (thus less traffic)
          example: false
          type: boolean
        relative:
          description: Enables relative comparison mode for API endpoints that have
            this feature.
          example: false
          type: boolean
        search:
          description: for some widgets, this enables sub-filtering based on searches
          type: string
        source:
          description: If specified, only compile data on this specific sourceID
          example: abcdef12345678
          type: string
        sources:
          description: for some widget, this fetches all sources
          type: boolean
        span:
          description: For factor charts, denotes the number of months to base factors
            on from
          example: 2
          type: integer
        subfilter:
          description: Quickly defined view by sub-filtering the existing view and
            matching on sourceURLs
          type: string
        to:
          description: If specified, only compile data up until here
          example: 1503483273
          type: integer
        types:
          description: If set, only return data from sources matching these types
          example:
          - jira
          - bugzilla
          type: array
        unique:
          description: Only compile data from unique commits, ignore duplicates
          type: boolean
        view:
          description: ID Of optional view to use
          example: abcdef12345678
          type: string
  securitySchemes:
    APIKeyAuth:
      in: headers
      name: APIKey
      type: apiKey
    cookieAuth:
      in: cookie
      name: warble_session
      type: apiKey
paths:
  /api/account:
    delete:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserName'
        description: User ID
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionCompleted'
          description: 200 response
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      security:
      - cookieAuth: []
      summary: Delete an account
    patch:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAccountEdit'
        description: User credentials
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionCompleted'
          description: 200 response
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      summary: Edit an account
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAccount'
        description: User credentials
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionCompleted'
          description: 200 response
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      summary: Create a new account
  /api/node/list:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeList'
          description: List of nodes in registry
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      summary: Lists the nodes in the registry
  /api/node/modify:
    delete:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodeDetails'
        description: Node to remove
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionCompleted'
          description: Node successfully removed from registry
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      summary: Deletes a registered node from the server
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodeDetails'
        description: Node details to modify
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionCompleted'
          description: Node successfully modified on server
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      summary: Modifies base data of a node in the registry
  /api/node/register:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodeCredentials'
        description: Node credentials
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyResult'
          description: Node successfully registered with server
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      summary: Registers a new node with the Warble server
  /api/node/status:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeDetails'
          description: Node status
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      summary: Displays the current status of a node
  /api/node/tasks:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskList'
          description: Node task list
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      summary: Returns a list of tasks assigned to a given node
  /api/session:
    delete:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Empty'
        description: Nada
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionCompleted'
          description: Logout successful
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      security:
      - cookieAuth: []
      summary: Log out (remove session)
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserData'
          description: 200 response
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      security:
      - cookieAuth: []
      summary: Display your login details
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCredentials'
        description: User credentials
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionCompleted'
          description: Login successful
          headers:
            Set-Cookie:
              schema:
                example: 77488a26-23c2-4e29-94a1-6a0738f6a3ff
                type: string
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      summary: Log in
  /api/widgets/{pageid}:
    get:
      parameters:
      - description: Page ID to fetch design for
        in: path
        name: pageid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetDesign'
          description: 200 Response
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      security:
      - cookieAuth: []
      summary: Shows the widget layout for a specific page