api.yml

# Status Site API
swagger: '2.0'
info:
  title: Status Site API
  description: |
    Collects, processes and provides various data regarding the status of 
    the services.
  version: "1.0.0"
host: status.dbogatov.org
securityDefinitions:
  apiauth:
    type: apiKey
    description: |
      The API key needed for authentication and authorization.
    name: apikey
    in: header
  userauth:
    type: basic
    authorizationUrl: /account/login
    description: |
      Cookie based authorization.
      User should login here: `/account/login` and upon successful login the cookie is returned.
schemes:
  - https
  - http
basePath: /api
produces:
  - application/json
  - text/plain
paths:
  
  /cpuload:
    post:
      summary: CPU Load data
      description: |
        CPU Load endpoint collects data regarding CPU load from different 
        sources. Particularly, a single number, CPU load percentage is expected.
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/plain
      parameters:
        - name: value
          in: formData
          description: Value of CPU load, percentage
          required: true
          type: integer
          format: int32
          example: 25
        - &SOURCE_PARAM
          name: source
          in: formData
          description: |
            The source of data. 
            Should uniquely represent the entity which sends the data. 
            For example, server identifier or website URL. 
            Has to satisfy regexp `[a-z0-9\\.\\-]+` and be no more than 32 characters long.
          required: true
          type: string
          format: string
          example: "the-server"
      security:
        - apiauth: ["status"]
        - userauth: ["status"]
      responses:
        401:
          &401
          description: Unauthorized. API Key is invalid or missing.
        400:
          &400
          description: Bad Request. One or more parameters are invalid or missing.
        200:
          &200
          description: OK. The data has been saved.
        default:
          &500
          description: Internal server error (500)
  
  /compilation:
    post:
      summary: Compilation stage completion report
      description: |
        Compilation endpoint collects data regarding completed compilations from different 
        sources. Particularly, source size, compilation time for a particular stage are expected.
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/plain
      parameters:
        - name: stage
          in: formData
          description: Compilation stage completed
          required: true
          type: string
          format: string
          enum:
            - "m4"
            - "sandpiper"
            - "simulation"
          example: "m4"
        - name: sourcesize
          in: formData
          description: Size of the source code in bytes
          required: true
          type: number
          format: int32
          example: "512256"
        - name: compiletime
          in: formData
          description: Time spent for compilation stage in milliseconds
          required: true
          type: number
          format: int32
          example: "659"
        - <<: *SOURCE_PARAM
      security:
        - apiauth: ["status"]
        - userauth: ["status"]
      responses:
        401:
          <<: *401
        400:
          <<: *400
        200:
          <<: *200
        default:
          <<: *500
  
  /logdata:
    post:
      summary: Report number and severity of generated log messages
      description: |
        Log Data endpoint collects data regarding log messages generated by different 
        sources. Particularly, message severity and count are expected.
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/plain
      parameters:
        - &SEVERITY_PARAM
          name: severity
          in: formData
          description: Message severity
          required: true
          type: string
          format: string
          enum:
            - "debug"
            - "detail"
            - "user"
            - "info"
            - "warn"
            - "error"
            - "fatal"
          example: "debug"
        - name: count
          in: formData
          description: Number of message of given severity generated
          required: false
          default: 1
          type: number
          format: int32
          example: 6
        - <<: *SOURCE_PARAM
      security:
        - apiauth: ["status"]
        - userauth: ["status"]
      responses:
        401:
          <<: *401
        400:
          <<: *400
        200:
          description: OK. The data has been saved.
        default:
          description: Internal server error (500)

  /logmessage:
    post:
      summary: Record a log message
      description: |
        Log Message endpoint collects log messages of different severities from different sources.
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/plain
      parameters:
        - <<: *SEVERITY_PARAM
        - name: auxiliarydata
          in: formData
          description: |
            Additional data, like metadata, not required for the log message.
            If provided, must be in a JSON format.
          required: false
          default: ""
          type: string
          format: string
          example: |
            {
              "Exception": "Cannot bind to port 80. Address already in use."
            }
        - name: message
          in: formData
          description: A message part of the log entry.
          required: true
          type: string
          format: string
          example: User with id 4568 has created a project with id 6868.
        - name: category
          in: formData
          description: |
            An integer representing a category (or type) of the log entry.
            Categorization is scoped and is up to the source.
          required: false
          default: 0
          type: number
          format: int32
          example: 6
        - <<: *SOURCE_PARAM
      security:
        - apiauth: ["status"]
        - userauth: ["status"]
      responses:
        401:
          <<: *401
        400:
          <<: *400
        200:
          <<: *200
        default:
          <<: *500

  /useraction:
    post:
      summary: User action report
      description: |
        User action enpoint collects data regarding user actions performed on different 
        sources. Particularly, user action and count are recorded.
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/plain
      parameters:
        - name: action
          in: formData
          description: |
            User Action as a string.
            <b>Note:</b> be consistent, "user-login" and "user login" will be considered different actions.
          required: true
          type: string
          format: string
          example: "login"
        - name: count
          in: formData
          description: Number of times given action was performed
          required: false
          default: 1
          type: number
          format: int32
          example: "6"
        - <<: *SOURCE_PARAM
      security:
        - apiauth: ["status"]
        - userauth: ["status"]
      responses:
        401:
          <<: *401
        400:
          <<: *400
        200:
          <<: *200
        default:
          <<: *500
  
  /getdata:
    get:
      summary: Retrieve status data
      description: |
        Get Data endpoint returns all available data that matches parameters.
      parameters:
        - &METRICTYPE_PARAM
          name: metrictype
          in: query
          description: |
            Metric type for which data is requested. 
          required: true
          type: string
          format: string
          enum:
            - "cpuload"
            - "useraction"
            - "compilation"
            - "log"
            - "ping"
          example: "cpuload"
        - <<: *SOURCE_PARAM
          in: query
        - name: timeperiod
          in: query
          description: |
            Number of seconds ago from which data is requested. 
            Default value is roughly a month.
          required: false
          default: 2592000
          type: integer
          fomat: int32
          example: 604800
      responses:
        401:
          <<: *401
        400:
          <<: *400
        404:
          description: |
            Not Found. The metric of given type (CPU load) and source does not 
            exist.
        200:
          description: OK. The data points are retrieved.
          schema:
            type: array
            items:
              $ref: '#/definitions/DataPoint'
          example:
            &DATAPOINT_EXAMPLE
              - timestamp: "2017-01-27T11:30:40.510739-05:00"
                value: 65
              - timestamp: "2017-01-27T11:30:40.510739-05:00"
                severity: "fatal"
                count: 5
              - timestamp: "2017-01-27T11:30:40.510739-05:00"
                severity: "login"
                count: 6
              - timestamp: "2017-01-27T11:30:40.510739-05:00"
                compiletime: 65482
                sourcesize: 4984634
                stage: "m4"
              - timestamp: "2017-01-27T11:30:40.510739-05:00"
                responsetime: 522
                httpstatuscode: 200
        204:
          &204
          description: |
            No Content. No errors are encountered and there are no data points 
            matching given criteria.
        default:
          <<: *500

  /health:
    get:
      summary: Get overall system health
      description: |
        Health endpoint returns the object that describes health of the system.
      responses:
        200:
          description: OK. The health report is retrieved.
          schema:
            $ref: '#/definitions/HealthReport'
          example:
            &HEALTH_REPORT_EXAMPLES
              - timestamp: "2017-01-27T11:30:40.510739-05:00"
                health: 95
                data:
                  &HEALTH_REPORT_DP_EXAMPLES
                    - type: cpuload
                      source: the-source
                      label: normal
                    - type: useraction
                      source: the-source
                      label: warning
        204:
          &204
          description: |
            No Content. No errors are encountered and there are no data points 
            matching given criteria.
        default:
          <<: *500

  /getmetrics:
    get:
      summary: Retrieve available metrics
      description: |
        Get Metrics endpoint returns available metrics (optionally filtered 
        by source and/or type parameters) which include metadata (eq. title)
        and numeric data (day-, hour- average, min, max, current value).
        <b>Note:</b> current value is always up-to-date (regardless of last 
        updated value).
      parameters:
        - <<: *METRICTYPE_PARAM
          required: false
        - <<: *SOURCE_PARAM
          required: false
          in: query
      responses:
        401:
          <<: *401
        200:
          description: OK. The metrics are retrieved.
          schema:
            type: array
            items:
              $ref: '#/definitions/Metric'
          example:
            &METRIC_EXAMPLES
              - source: "http://makerchip.com"
                title: "Web service response time"
                autolabel:
                  &LABEL_EXAMPLE_1
                    title: Minor degradation
                    severity: warning
                manuallabel: 
                  &LABEL_EXAMPLE_2
                    title: We are investigating
                    severity: investigating
                daymin: 100
                daymax: 500
                dayavg: 300
                hourmin: 150
                hourmax: 400
                houravg: 200
                currentvalue: 350
                lastupdated: "2017-01-27T11:30:40.510739-05:00"
              - source: "compilation-server-13"
                title: "CPU Load"
                autolabel:
                  &LABEL_EXAMPLE_3
                    title: Normal operation
                    severity: normal
                manuallabel:
                  &LABEL_EXAMPLE_4
                    title: ""
                    severity: none
                daymin: 1
                daymax: 70
                dayavg: 25
                hourmin: 1
                hourmax: 30
                houravg: 20
                currentvalue: 15
                lastupdated: "2017-01-27T11:30:45.510739-05:00"
        204:
          <<: *204
        default:
          <<: *500

  /getlogmessages:
    get:
      summary: Retrieve available log messages
      description: |
        Get Log Messages endpoint returns all available log messages.
      parameters:
        - name: sources
          in: query
          description: |
            Coma separated collection of source names used to filter log messages.
            If not provided, log messages will not be filtered by source.
          required: false
          default: ""
          type: string
          fomat: string
          example: "source-1,source-2"
        - name: categories
          in: query
          description: |
            Coma separated collection of categories used to filter log messages.
            If not provided, log messages will not be filtered by category.
          required: false
          default: ""
          type: string
          fomat: string
          example: "1,2"
        - name: severities
          in: query
          description: |
            Coma separated collection of severities used to filter log messages.
            If not provided, log messages will not be filtered by severity.
            List of severities is the same as input enumeration for "logmessage" endpoint.
          required: false
          default: ""
          type: string
          fomat: string
          example: "info,warn"
        - name: keywords
          in: query
          description: |
            Coma separated collection of words used to filter log messages.
            If not provided, log messages will not be filtered by keywords.
            Log message body and auxillary data will be searched for keywords.
            If and only if any keyword exists in log message, the message will be included in the output.
            Keywords may not contain white spaces.
          required: false
          default: ""
          type: string
          fomat: string
          example: "user,login"
        - name: start
          in: query
          description: |
            Date and time from which to include log messages.
            Timestamp is formatted as the number of milliseconds since Jan 1, 1970.
            If not provided, log messages will not be filtered by start date.
          required: false
          default: ""
          type: string
          fomat: string
          example: "1494440378000"
        - name: end
          in: query
          description: |
            Date and time to which to include log messages.
            Timestamp is formatted as the number of milliseconds since Jan 1, 1970.
            If not provided, log messages will not be filtered by end date.
          required: false
          default: ""
          type: string
          fomat: string
          example: "1494440378000"
      security:
        - apiauth: ["status"]
        - userauth: ["status"]
      responses:
        401:
          <<: *401
        200:
          description: OK. The log messages are retrieved.
          schema:
            type: array
            items:
              $ref: '#/definitions/LogMessage'
          example:
            &LOGMESSAGE_EXAMPLES
              - source: compilation-server-13
                id: 4564
                message: User with id 4568 has created a project with id 6868.
                auxiliarydata: ""
                severity: "Information"
                category: 5
                timestamp: "2017-01-27T11:30:40.510739-05:00"
              - source: http-server-15
                id: 1002
                message: Server startup failed.
                auxiliarydata: |
                  {
                    "Exception": "Cannot bind to port 80. Address already in use."
                  }
                severity: "Fatal error"
                category: 6
                timestamp: "2017-01-27T11:30:45.510739-05:00"
        204:
          <<: *204
        default:
          <<: *500
        
  /removemetric:
    delete:
      summary: Remove a metric
      description: |
        Remove Metric endpoint removes a metric from the system.
      produces:
        - text/plain
      parameters:
        - <<: *METRICTYPE_PARAM
        - <<: *SOURCE_PARAM
          in: query
      security:
        - apiauth: ["status"]
        - userauth: ["status"]
      responses:
        401:
          <<: *401
        400:
          <<: *400
        404:
          description: |
            Not Found. The metric of given type and source does not 
            exist.
        200:
          description: OK. The metric has been removed.
        default:
          <<: *500
  
  /metricupdate:
    patch:
      summary: Modify a metric
      description: |
        Metric Update endpoint changes the existing metric in the system.
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/plain
      parameters:
        - <<: *METRICTYPE_PARAM
          in: formData
        - <<: *SOURCE_PARAM
        - name: manuallabelid
          in: formData
          description: |
            An ID of the manual label to set for the metric.
          required: true
          type: integer
          fomat: int32
          example: "2"
        - name: public
          in: formData
          description: |
            A boolean indicating if the metric should be public or not.
            Tru for public, false for private.
          required: true
          type: boolean
          example: "true"
      security:
        - apiauth: ["status"]
        - userauth: ["status"]
      responses:
        401:
          <<: *401
        400:
          <<: *400
        404:
          description: |
            Not Found. The metric of given type and source does not 
            exist. Or the manual label of given ID does not exist.
        200:
          description: OK. The metric has been updated.
        default:
          <<: *500

definitions:

  LogMessage:
    type: object
    required:
      - source
      - id
      - message
      - auxiliarydata
      - severity
      - category
      - timestamp
    properties:
      source:
        type: string        
        description: The source of the metric (eq. server identifier or url)
      timestamp:
        type: string
        description: Timestamp when log entry was recorded.
      id:
        type: number
        description: Unique identifier for the log entry.
      message:
        type: string
        description: A message part of the log entry.
      auxiliarydata:
        type: string
        description: |
          Additional data, like metadata, not required for the log message.
          Given in a JSON format.
      severity:
        type: string
        description: Log entry severity (eq. warn or error)
      category:
        type: number
        description: |
          An integer representing a category (or type) of the log entry.
          Categorization is scoped and is up to the source.
    example:
      *LOGMESSAGE_EXAMPLES

  Label:
    type: object
    required:
      - title
      - severity
    properties:
      title:
        type: string
        description: text part of the label
      severity:
        type: string
        description: string representation of severity of the label
    example:
      - <<: *LABEL_EXAMPLE_1
      - <<: *LABEL_EXAMPLE_2
      - <<: *LABEL_EXAMPLE_3
      - <<: *LABEL_EXAMPLE_4

  Metric:
    type: object
    required:
      - source
      - title
      - autolabel
      - manuallabel
      - daymin
      - daymax
      - dayavg
      - hourmin
      - hourmax
      - houravg
      - currentvalue
    properties:
      source:
        type: string        
        description: The source of the metric (eq. server identifier or url)
      title:
        type: string
        description: Human readable title of the metric (eq. CPU Load).
      autolabel:
        type: Label
        description: The label assigned to the metric automatically by the system (eq. Normal operation)
      manuallabel:
        type: Label
        description: The label assigned to the metric manually by the administrator (eq. We are investigating the issue)
      daymin:
        type: number
        description: The lowest numberic value of the metric in a timerange from now to a day ago
      daymax:
        type: number
        description: The highest numberic value of the metric in a timerange from now to a day ago
      dayavg:
        type: number
        description: The average of the numberic values of the metric in a timerange from now to a day ago
      hourmin:
        type: number
        description: The lowest numberic value of the metric in a timerange from now to an hour ago
      hourmax:
        type: number
        description: The highest numberic value of the metric in a timerange from now to an hour ago
      houravg:
        type: number
        description: The average of the numberic values of the metric in a timerange from now to an hour ago
      currentvalue:
        type: number
        description: The most recent value of the metric
      lastupdated:
        type: string
        description: |
          Timestamp when metric values (except currentvalue) were updated.
          currentvalue is always up to date.
    example:
      *METRIC_EXAMPLES

  HealthReport:
    type: object
    required:
      - timestamp
      - health
      - data
    properties:
      timestamp:
        type: string        
        description: |
          Timestamp when this report was generated.
          May not be eqaul to current timestamp.
          Reports are generated periodically and are cached.
      health:
        type: integer
        description: Health value (percent).
      data:
        type: array
        description: List of HealthReportDataPoint.
        items:
          $ref: "#/definitions/HealthReportDataPoint"
    example:
      *HEALTH_REPORT_EXAMPLES

  HealthReportDataPoint:
    type: object
    required:
      - type
      - source
      - label
    properties:
      type: 
        type: string
        description: Metric type (eq. cpuload)
      source: 
        type: string
        description: Metric source
      label: 
        type: string
        description: Metric label (eq. normal)
    example:
      *HEALTH_REPORT_DP_EXAMPLES

  DataPoint:
    # Wanted oneOf thing, but here is the PR: https://github.com/OAI/OpenAPI-Specification/pull/741
    type: object
    required:
      - timestamp
    properties:
      timestamp:
        type: string        
        description: Timestamp when data point was recorded.
      value:
        type: integer
        description: The value of a **numeric** data point.
      severity:
        type: string
        description: The severity of a log message in a **log** data point.
      count:
        type: number
        description: The number of items in a **log** or **useraction** data point.
      useraction:
        type: string
        description: The action performed by user in a **useraction** data point.
      compiletime:
        type: number
        description: The number of milliseconds taken for compilation in a **compilation** data point.
      sourcesize: 
        type: number
        description: The size of the source file in bytes in a **compilation** data point.
      stage:
        type: string
        description: The compilation stage in a **compilation** data point.
      responsetime:
        type: number
        description: The response time in milliseconds in a **ping** data point.
      httpstatuscode:
        type: number
        description: The status code of a response in a **ping** data point.
    example:
      *DATAPOINT_EXAMPLE