Status Site API API Reference

Collects, processes and provides various data regarding the status of the services.

API Endpoint
https://status.dbogatov.org/api
Response Content-Types: application/json, text/plain
Schemes: https, http
Version: 1.0.0

Authentication

apiauth

description

The API key needed for authentication and authorization.

name
apikey
in
header

userauth

authorizationUrl
/account/login
description

Cookie based authorization. User should login here: /account/login and upon successful login the cookie is returned.

Paths

CPU Load data

POST /cpuload

CPU Load endpoint collects data regarding CPU load from different sources. Particularly, a single number, CPU load percentage is expected.

value

Value of CPU load, percentage

type
integer (int32)
in
formData
source

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.

type
string (string)
in
formData
200 OK

OK. The data has been saved.

400 Bad Request

Bad Request. One or more parameters are invalid or missing.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

default

Internal server error (500)

Response Content-Types: text/plain
apiauth status
userauth status

Compilation stage completion report

POST /compilation

Compilation endpoint collects data regarding completed compilations from different sources. Particularly, source size, compilation time for a particular stage are expected.

stage

Compilation stage completed

type
string (string) m4, sandpiper, simulation
in
formData
sourcesize

Size of the source code in bytes

type
number (int32)
in
formData
compiletime

Time spent for compilation stage in milliseconds

type
number (int32)
in
formData
source

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.

type
string (string)
in
formData
200 OK

OK. The data has been saved.

400 Bad Request

Bad Request. One or more parameters are invalid or missing.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

default

Internal server error (500)

Response Content-Types: text/plain
apiauth status
userauth status

Report number and severity of generated log messages

POST /logdata

Log Data endpoint collects data regarding log messages generated by different sources. Particularly, message severity and count are expected.

severity

Message severity

type
string (string) debug, detail, user, info, warn, error, fatal
in
formData
count

Number of message of given severity generated

type
number (int32) 1
in
formData
source

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.

type
string (string)
in
formData
200 OK

OK. The data has been saved.

400 Bad Request

Bad Request. One or more parameters are invalid or missing.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

default

Internal server error (500)

Response Content-Types: text/plain
apiauth status
userauth status

Record a log message

POST /logmessage

Log Message endpoint collects log messages of different severities from different sources.

severity

Message severity

type
string (string) debug, detail, user, info, warn, error, fatal
in
formData
auxiliarydata

Additional data, like metadata, not required for the log message. If provided, must be in a JSON format.

type
string (string)
in
formData
message

A message part of the log entry.

type
string (string)
in
formData
category

An integer representing a category (or type) of the log entry. Categorization is scoped and is up to the source.

type
number (int32) 0
in
formData
source

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.

type
string (string)
in
formData
200 OK

OK. The data has been saved.

400 Bad Request

Bad Request. One or more parameters are invalid or missing.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

default

Internal server error (500)

Response Content-Types: text/plain
apiauth status
userauth status

User action report

POST /useraction

User action enpoint collects data regarding user actions performed on different sources. Particularly, user action and count are recorded.

action

User Action as a string. Note: be consistent, "user-login" and "user login" will be considered different actions.

type
string (string)
in
formData
count

Number of times given action was performed

type
number (int32) 1
in
formData
source

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.

type
string (string)
in
formData
200 OK

OK. The data has been saved.

400 Bad Request

Bad Request. One or more parameters are invalid or missing.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

default

Internal server error (500)

Response Content-Types: text/plain
apiauth status
userauth status

Retrieve status data

GET /getdata

Get Data endpoint returns all available data that matches parameters.

metrictype

Metric type for which data is requested.

type
string (string) cpuload, useraction, compilation, log, ping
in
query
source

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.

type
string (string)
in
query
timeperiod

Number of seconds ago from which data is requested. Default value is roughly a month.

type
integer 2592000
in
query
200 OK
DataPoint

OK. The data points are retrieved.

204 No Content

No Content. No errors are encountered and there are no data points matching given criteria.

400 Bad Request

Bad Request. One or more parameters are invalid or missing.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

404 Not Found

Not Found. The metric of given type (CPU load) and source does not exist.

default

Internal server error (500)

Response Example (200 OK) 
[
  {
    "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
  }
]

Get overall system health

GET /health

Health endpoint returns the object that describes health of the system.

200 OK
HealthReport

OK. The health report is retrieved.

204 No Content

No Content. No errors are encountered and there are no data points matching given criteria.

default

Internal server error (500)

Response Example (200 OK) 
[
  {
    "timestamp": "2017-01-27T11:30:40.510739-05:00",
    "health": 95,
    "data": [
      {
        "type": "cpuload",
        "source": "the-source",
        "label": "normal"
      },
      {
        "type": "useraction",
        "source": "the-source",
        "label": "warning"
      }
    ]
  }
]

Retrieve available metrics

GET /getmetrics

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). Note: current value is always up-to-date (regardless of last updated value).

metrictype

Metric type for which data is requested.

type
string (string) cpuload, useraction, compilation, log, ping
in
query
source

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.

type
string (string)
in
query
200 OK
Metric

OK. The metrics are retrieved.

204 No Content

No Content. No errors are encountered and there are no data points matching given criteria.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

default

Internal server error (500)

Response Example (200 OK) 
[
  {
    "source": "http://makerchip.com",
    "title": "Web service response time",
    "autolabel": {
      "title": "Minor degradation",
      "severity": "warning"
    },
    "manuallabel": {
      "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": {
      "title": "Normal operation",
      "severity": "normal"
    },
    "manuallabel": {
      "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"
  }
]

Retrieve available log messages

GET /getlogmessages

Get Log Messages endpoint returns all available log messages.

sources

Coma separated collection of source names used to filter log messages. If not provided, log messages will not be filtered by source.

type
string
in
query
categories

Coma separated collection of categories used to filter log messages. If not provided, log messages will not be filtered by category.

type
string
in
query
severities

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.

type
string
in
query
keywords

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.

type
string
in
query
start

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.

type
string
in
query
end

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.

type
string
in
query
200 OK
LogMessage

OK. The log messages are retrieved.

204 No Content

No Content. No errors are encountered and there are no data points matching given criteria.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

default

Internal server error (500)

Response Example (200 OK) 
[
  {
    "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": "{\n  \"Exception\": \"Cannot bind to port 80. Address already in use.\"\n}\n",
    "severity": "Fatal error",
    "category": 6,
    "timestamp": "2017-01-27T11:30:45.510739-05:00"
  }
]
apiauth status
userauth status

Remove a metric

DELETE /removemetric

Remove Metric endpoint removes a metric from the system.

metrictype

Metric type for which data is requested.

type
string (string) cpuload, useraction, compilation, log, ping
in
query
source

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.

type
string (string)
in
query
200 OK

OK. The metric has been removed.

400 Bad Request

Bad Request. One or more parameters are invalid or missing.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

404 Not Found

Not Found. The metric of given type and source does not exist.

default

Internal server error (500)

Response Content-Types: text/plain
apiauth status
userauth status

Modify a metric

PATCH /metricupdate

Metric Update endpoint changes the existing metric in the system.

metrictype

Metric type for which data is requested.

type
string (string) cpuload, useraction, compilation, log, ping
in
formData
source

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.

type
string (string)
in
formData
manuallabelid

An ID of the manual label to set for the metric.

type
integer
in
formData
public

A boolean indicating if the metric should be public or not. Tru for public, false for private.

type
boolean
in
formData
200 OK

OK. The metric has been updated.

400 Bad Request

Bad Request. One or more parameters are invalid or missing.

401 Unauthorized

Unauthorized. API Key is invalid or missing.

404 Not Found

Not Found. The metric of given type and source does not exist. Or the manual label of given ID does not exist.

default

Internal server error (500)

Response Content-Types: text/plain
apiauth status
userauth status

Schema Definitions

LogMessage: object

source: string

The source of the metric (eq. server identifier or url)

timestamp: string

Timestamp when log entry was recorded.

id: number

Unique identifier for the log entry.

message: string

A message part of the log entry.

auxiliarydata: string

Additional data, like metadata, not required for the log message. Given in a JSON format.

severity: string

Log entry severity (eq. warn or error)

category: number

An integer representing a category (or type) of the log entry. Categorization is scoped and is up to the source.

Example
[
  {
    "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": "{\n  \"Exception\": \"Cannot bind to port 80. Address already in use.\"\n}\n",
    "severity": "Fatal error",
    "category": 6,
    "timestamp": "2017-01-27T11:30:45.510739-05:00"
  }
]

Label: object

title: string

text part of the label

severity: string

string representation of severity of the label

Example
[
  {
    "title": "Minor degradation",
    "severity": "warning"
  },
  {
    "title": "We are investigating",
    "severity": "investigating"
  },
  {
    "title": "Normal operation",
    "severity": "normal"
  },
  {
    "title": "",
    "severity": "none"
  }
]

Metric: object

source: string

The source of the metric (eq. server identifier or url)

title: string

Human readable title of the metric (eq. CPU Load).

autolabel: Label

The label assigned to the metric automatically by the system (eq. Normal operation)

manuallabel: Label

The label assigned to the metric manually by the administrator (eq. We are investigating the issue)

daymin: number

The lowest numberic value of the metric in a timerange from now to a day ago

daymax: number

The highest numberic value of the metric in a timerange from now to a day ago

dayavg: number

The average of the numberic values of the metric in a timerange from now to a day ago

hourmin: number

The lowest numberic value of the metric in a timerange from now to an hour ago

hourmax: number

The highest numberic value of the metric in a timerange from now to an hour ago

houravg: number

The average of the numberic values of the metric in a timerange from now to an hour ago

currentvalue: number

The most recent value of the metric

lastupdated: string

Timestamp when metric values (except currentvalue) were updated. currentvalue is always up to date.

Example
[
  {
    "source": "http://makerchip.com",
    "title": "Web service response time",
    "autolabel": {
      "title": "Minor degradation",
      "severity": "warning"
    },
    "manuallabel": {
      "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": {
      "title": "Normal operation",
      "severity": "normal"
    },
    "manuallabel": {
      "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"
  }
]

HealthReport: object

timestamp: string

Timestamp when this report was generated. May not be eqaul to current timestamp. Reports are generated periodically and are cached.

health: integer

Health value (percent).

data: HealthReportDataPoint

List of HealthReportDataPoint.

Example
[
  {
    "timestamp": "2017-01-27T11:30:40.510739-05:00",
    "health": 95,
    "data": [
      {
        "type": "cpuload",
        "source": "the-source",
        "label": "normal"
      },
      {
        "type": "useraction",
        "source": "the-source",
        "label": "warning"
      }
    ]
  }
]

HealthReportDataPoint: object

type: string

Metric type (eq. cpuload)

source: string

Metric source

label: string

Metric label (eq. normal)

Example
[
  {
    "type": "cpuload",
    "source": "the-source",
    "label": "normal"
  },
  {
    "type": "useraction",
    "source": "the-source",
    "label": "warning"
  }
]

DataPoint: object

timestamp: string

Timestamp when data point was recorded.

value: integer

The value of a numeric data point.

severity: string

The severity of a log message in a log data point.

count: number

The number of items in a log or useraction data point.

useraction: string

The action performed by user in a useraction data point.

compiletime: number

The number of milliseconds taken for compilation in a compilation data point.

sourcesize: number

The size of the source file in bytes in a compilation data point.

stage: string

The compilation stage in a compilation data point.

responsetime: number

The response time in milliseconds in a ping data point.

httpstatuscode: number

The status code of a response in a ping data point.

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
  }
]
Documentation by Spectacle