diff options
Diffstat (limited to 'web/api/netdata-swagger.json')
| -rw-r--r-- | web/api/netdata-swagger.json | 316 |
1 files changed, 240 insertions, 76 deletions
diff --git a/web/api/netdata-swagger.json b/web/api/netdata-swagger.json index 1a0ec8638..8ec0a3121 100644 --- a/web/api/netdata-swagger.json +++ b/web/api/netdata-swagger.json @@ -21,13 +21,13 @@ "description": "The info endpoint returns basic information about netdata. It provides:\n* netdata version\n* netdata unique id\n* list of hosts mirrored (includes itself)\n* Operating System, Virtualization and Container technology information\n* List of active collector plugins and modules\n* number of alarms in the host\n * number of alarms in normal state\n * number of alarms in warning state\n * number of alarms in critical state\n", "responses": { "200": { - "description": "netdata basic information", + "description": "netdata basic information.", "schema": { "$ref": "#/definitions/info" } }, "503": { - "description": "netdata daemon not ready (used for health checks)" + "description": "netdata daemon not ready (used for health checks)." } } } @@ -38,7 +38,7 @@ "description": "The charts endpoint returns a summary about all charts stored in the netdata server.", "responses": { "200": { - "description": "An array of charts", + "description": "An array of charts.", "schema": { "type": "array", "items": { @@ -71,6 +71,9 @@ "$ref": "#/definitions/chart" } }, + "400": { + "description": "No chart id was supplied in the request." + }, "404": { "description": "No chart with the given id is found." } @@ -80,7 +83,7 @@ "/alarm_variables": { "get": { "summary": "List variables available to configure alarms for a chart", - "description": "Returns the basic information of a chart and all the variables that can be used in alarm and template health configurations for the particular chart or family", + "description": "Returns the basic information of a chart and all the variables that can be used in alarm and template health configurations for the particular chart or family.", "parameters": [ { "name": "chart", @@ -93,7 +96,7 @@ ], "responses": { "200": { - "description": "A javascript object with information about the chart and the available variables", + "description": "A javascript object with information about the chart and the available variables.", "schema": { "$ref": "#/definitions/alarm_variables" } @@ -113,7 +116,7 @@ "/data": { "get": { "summary": "Get collected data for a specific chart", - "description": "The Data endpoint returns data stored in the round robin database of a chart.\n", + "description": "The data endpoint returns data stored in the round robin database of a chart.", "parameters": [ { "name": "chart", @@ -128,7 +131,7 @@ { "name": "dimension", "in": "query", - "description": "zero, one or more dimension ids or names, as returned by the /chart call, separated with comma or pipe. Netdata simple patterns are supported.", + "description": "Zero, one or more dimension ids or names, as returned by the /chart call, separated with comma or pipe. Netdata simple patterns are supported.", "required": false, "type": "array", "items": { @@ -281,9 +284,9 @@ ], "responses": { "200": { - "description": "The call was successful. The response should include the data.", + "description": "The call was successful. The response includes the data in the format requested. Swagger2.0 does not process the discriminator field to show polymorphism. The response will be one of the sub-types of the data-schema according to the chosen format, e.g. json -> data_json.", "schema": { - "$ref": "#/definitions/chart" + "$ref": "#/definitions/data" } }, "400": { @@ -301,7 +304,7 @@ "/badge.svg": { "get": { "summary": "Generate a SVG image for a chart (or dimension)", - "description": "Successful responses are SVG images\n", + "description": "Successful responses are SVG images.", "parameters": [ { "name": "chart", @@ -316,7 +319,7 @@ { "name": "alarm", "in": "query", - "description": "the name of an alarm linked to the chart", + "description": "The name of an alarm linked to the chart.", "required": false, "type": "string", "format": "any text", @@ -325,7 +328,7 @@ { "name": "dimension", "in": "query", - "description": "zero, one or more dimension ids, as returned by the /chart call.", + "description": "Zero, one or more dimension ids, as returned by the /chart call.", "required": false, "type": "array", "items": { @@ -399,7 +402,7 @@ { "name": "label", "in": "query", - "description": "a text to be used as the label", + "description": "A text to be used as the label.", "required": false, "type": "string", "format": "any text", @@ -408,7 +411,7 @@ { "name": "units", "in": "query", - "description": "a text to be used as the units", + "description": "A text to be used as the units.", "required": false, "type": "string", "format": "any text", @@ -417,7 +420,7 @@ { "name": "label_color", "in": "query", - "description": "a color to be used for the background of the label", + "description": "A color to be used for the background of the label.", "required": false, "type": "string", "format": "any text", @@ -426,7 +429,7 @@ { "name": "value_color", "in": "query", - "description": "a color to be used for the background of the label. You can set multiple using a pipe with a condition each, like this: color<value|color>value|color:null The following operators are supported: >, <, >=, <=, =, :null (to check if no value exists).", + "description": "A color to be used for the background of the label. You can set multiple using a pipe with a condition each, like this: color<value|color>value|color:null The following operators are supported: >, <, >=, <=, =, :null (to check if no value exists).", "required": false, "type": "string", "format": "any text", @@ -435,7 +438,7 @@ { "name": "multiply", "in": "query", - "description": "multiply the value with this number for rendering it at the image (integer value required)", + "description": "Multiply the value with this number for rendering it at the image (integer value required).", "required": false, "type": "number", "format": "integer", @@ -444,7 +447,7 @@ { "name": "divide", "in": "query", - "description": "divide the value with this number for rendering it at the image (integer value required)", + "description": "Divide the value with this number for rendering it at the image (integer value required).", "required": false, "type": "number", "format": "integer", @@ -453,7 +456,7 @@ { "name": "scale", "in": "query", - "description": "set the scale of the badge (greater or equal to 100)", + "description": "Set the scale of the badge (greater or equal to 100).", "required": false, "type": "number", "format": "integer", @@ -479,12 +482,12 @@ "/allmetrics": { "get": { "summary": "Get a value of all the metrics maintained by netdata", - "description": "The charts endpoint returns the latest value of all charts and dimensions stored in the netdata server.", + "description": "The allmetrics endpoint returns the latest value of all charts and dimensions stored in the netdata server.", "parameters": [ { "name": "format", "in": "query", - "description": "The format of the response to be returned", + "description": "The format of the response to be returned.", "required": true, "type": "string", "enum": [ @@ -498,7 +501,7 @@ { "name": "help", "in": "query", - "description": "enable or disable HELP lines in prometheus output", + "description": "Enable or disable HELP lines in prometheus output.", "required": false, "type": "string", "enum": [ @@ -510,7 +513,7 @@ { "name": "types", "in": "query", - "description": "enable or disable TYPE lines in prometheus output", + "description": "Enable or disable TYPE lines in prometheus output.", "required": false, "type": "string", "enum": [ @@ -522,7 +525,7 @@ { "name": "timestamps", "in": "query", - "description": "enable or disable timestamps in prometheus output", + "description": "Enable or disable timestamps in prometheus output.", "required": false, "type": "string", "enum": [ @@ -546,7 +549,7 @@ { "name": "oldunits", "in": "query", - "description": "When enabled, netdata will show metric names for the default source=average as they appeared before 1.12, by using the legacy unit naming conventions", + "description": "When enabled, netdata will show metric names for the default source=average as they appeared before 1.12, by using the legacy unit naming conventions.", "required": false, "type": "string", "enum": [ @@ -586,7 +589,7 @@ { "name": "data", "in": "query", - "description": "Select the prometheus response data source. The default is controlled in netdata.conf", + "description": "Select the prometheus response data source. There is a setting in netdata.conf for the default.", "required": false, "type": "string", "enum": [ @@ -599,10 +602,10 @@ ], "responses": { "200": { - "description": "All the metrics returned in the format requested" + "description": "All the metrics returned in the format requested." }, "400": { - "description": "The format requested is not supported" + "description": "The format requested is not supported." } } } @@ -615,7 +618,7 @@ { "name": "all", "in": "query", - "description": "If passed, all enabled alarms are returned", + "description": "If passed, all enabled alarms are returned.", "required": false, "type": "boolean", "allowEmptyValue": true @@ -623,7 +626,7 @@ ], "responses": { "200": { - "description": "An object containing general info and a linked list of alarms", + "description": "An object containing general info and a linked list of alarms.", "schema": { "$ref": "#/definitions/alarms" } @@ -639,14 +642,14 @@ { "name": "after", "in": "query", - "description": "Passing the parameter after=UNIQUEID returns all the events in the alarm log that occurred after UNIQUEID. An automated series of calls would call the interface once without after=, store the last UNIQUEID of the returned set, and give it back to get incrementally the next events", + "description": "Passing the parameter after=UNIQUEID returns all the events in the alarm log that occurred after UNIQUEID. An automated series of calls would call the interface once without after=, store the last UNIQUEID of the returned set, and give it back to get incrementally the next events.", "required": false, "type": "integer" } ], "responses": { "200": { - "description": "An array of alarm log entries", + "description": "An array of alarm log entries.", "schema": { "type": "array", "items": { @@ -665,7 +668,7 @@ { "in": "query", "name": "context", - "description": "Specify context which should be checked", + "description": "Specify context which should be checked.", "required": false, "allowEmptyValue": true, "type": "array", @@ -680,7 +683,7 @@ { "in": "query", "name": "status", - "description": "Specify alarm status to count", + "description": "Specify alarm status to count.", "required": false, "allowEmptyValue": true, "type": "string", @@ -698,7 +701,7 @@ ], "responses": { "200": { - "description": "An object containing a count of alarms with given status for given contexts", + "description": "An object containing a count of alarms with given status for given contexts.", "schema": { "type": "array", "items": { @@ -741,7 +744,7 @@ { "name": "chart", "in": "query", - "description": "Chart ids/names, as shown on the dashboard. These will match the `on` entry of a configured `alarm`", + "description": "Chart ids/names, as shown on the dashboard. These will match the `on` entry of a configured `alarm`.", "type": "string" }, { @@ -765,7 +768,7 @@ ], "responses": { "200": { - "description": "A plain text response based on the result of the command" + "description": "A plain text response based on the result of the command." }, "403": { "description": "Bearer authentication error." @@ -790,7 +793,7 @@ }, "mirrored_hosts": { "type": "array", - "description": "list of hosts mirrored of the server (include itself).", + "description": "List of hosts mirrored of the server (include itself).", "items": { "type": "string" }, @@ -801,83 +804,83 @@ }, "os_name": { "type": "string", - "description": "Operating System Name", + "description": "Operating System Name.", "example": "Manjaro Linux" }, "os_id": { "type": "string", - "description": "Operating System ID", + "description": "Operating System ID.", "example": "manjaro" }, "os_id_like": { "type": "string", - "description": "Known OS similar to this OS", + "description": "Known OS similar to this OS.", "example": "arch" }, "os_version": { "type": "string", - "description": "Operating System Version", + "description": "Operating System Version.", "example": "18.0.4" }, "os_version_id": { "type": "string", - "description": "Operating System Version ID", + "description": "Operating System Version ID.", "example": "unknown" }, "os_detection": { "type": "string", - "description": "OS parameters detection method", + "description": "OS parameters detection method.", "example": "Mixed" }, "kernel_name": { "type": "string", - "description": "Kernel Name", + "description": "Kernel Name.", "example": "Linux" }, "kernel_version": { "type": "string", - "description": "Kernel Version", + "description": "Kernel Version.", "example": "4.19.32-1-MANJARO" }, "architecture": { "type": "string", - "description": "Kernel architecture", + "description": "Kernel architecture.", "example": "x86_64" }, "virtualization": { "type": "string", - "description": "Virtualization Type", + "description": "Virtualization Type.", "example": "kvm" }, "virt_detection": { "type": "string", - "description": "Virtualization detection method", + "description": "Virtualization detection method.", "example": "systemd-detect-virt" }, "container": { "type": "string", - "description": "Container technology", + "description": "Container technology.", "example": "docker" }, "container_detection": { "type": "string", - "description": "Container technology detection method", + "description": "Container technology detection method.", "example": "dockerenv" }, "collectors": { "type": "array", "items": { "type": "object", - "description": "Array of collector plugins and modules", + "description": "Array of collector plugins and modules.", "properties": { "plugin": { "type": "string", - "description": "Collector plugin", + "description": "Collector plugin.", "example": "python.d.plugin" }, "module": { "type": "string", - "description": "Module of the collector plugin", + "description": "Module of the collector plugin.", "example": "dockerd" } } @@ -885,19 +888,19 @@ }, "alarms": { "type": "object", - "description": "number of alarms in the server.", + "description": "Number of alarms in the server.", "properties": { "normal": { "type": "integer", - "description": "number of alarms in normal state." + "description": "Number of alarms in normal state." }, "warning": { "type": "integer", - "description": "number of alarms in warning state." + "description": "Number of alarms in warning state." }, "critical": { "type": "integer", - "description": "number of alarms in critical state." + "description": "Number of alarms in critical state." } } } @@ -914,6 +917,15 @@ "type": "string", "description": "netdata version of the server." }, + "release_channel": { + "type": "string", + "description": "The release channel of the build on the server.", + "example": "nightly" + }, + "timezone": { + "type": "string", + "description": "The current timezone on the server." + }, "os": { "type": "string", "description": "The netdata server host operating system.", @@ -927,6 +939,10 @@ "type": "number", "description": "The duration, in seconds, of the round robin database maintained by netdata." }, + "memory_mode": { + "type": "string", + "description": "The name of the database memory mode on the server." + }, "update_every": { "type": "number", "description": "The default update frequency of the netdata server. All charts have an update frequency equal or bigger than this." @@ -963,11 +979,11 @@ "properties": { "id": { "type": "string", - "description": "The unique id of the chart" + "description": "The unique id of the chart." }, "name": { "type": "string", - "description": "The name of the chart" + "description": "The name of the chart." }, "type": { "type": "string", @@ -1041,11 +1057,11 @@ }, "green": { "type": "number", - "description": "Chart health green threshold" + "description": "Chart health green threshold." }, "red": { "type": "number", - "description": "Chart health red trheshold" + "description": "Chart health red threshold." } } }, @@ -1054,15 +1070,15 @@ "properties": { "chart": { "type": "string", - "description": "The unique id of the chart" + "description": "The unique id of the chart." }, "chart_name": { "type": "string", - "description": "The name of the chart" + "description": "The name of the chart." }, "cnart_context": { "type": "string", - "description": "The context of the chart. It is shared across multiple monitored software or hardware instances and used in alarm templates" + "description": "The context of the chart. It is shared across multiple monitored software or hardware instances and used in alarm templates." }, "family": { "type": "string", @@ -1126,24 +1142,26 @@ "properties": { "name": { "type": "string", - "description": "The name of the dimension" + "description": "The name of the dimension." } } }, - "json_wrap": { + "data": { "type": "object", + "discriminator": "format", + "description": "Response will contain the appropriate subtype, e.g. data_json depending on the requested format.", "properties": { "api": { "type": "number", - "description": "The API version this conforms to, currently 1" + "description": "The API version this conforms to, currently 1." }, "id": { "type": "string", - "description": "The unique id of the chart" + "description": "The unique id of the chart." }, "name": { "type": "string", - "description": "The name of the chart" + "description": "The name of the chart." }, "update_every": { "type": "number", @@ -1224,12 +1242,158 @@ "$ref": "#/definitions/chart_variables" } } - }, - "result": { - "description": "The result requested, in the format requested." } } }, + "data_json": { + "description": "Data response in json format.", + "allOf": [ + { + "$ref": "#/definitions/data" + }, + { + "properties": { + "result": { + "type": "object", + "properties": { + "labels": { + "description": "The dimensions retrieved from the chart.", + "type": "array", + "items": { + "type": "string" + } + }, + "data": { + "description": "The data requested, one element per sample with each element containing the values of the dimensions described in the labels value.", + "type": "array", + "items": { + "type": "number" + } + } + }, + "description": "The result requested, in the format requested." + } + } + } + ] + }, + "data_flat": { + "description": "Data response in csv / tsv / tsv-excel / ssv / ssv-comma / markdown / html formats.", + "allOf": [ + { + "$ref": "#/definitions/data" + }, + { + "properties": { + "result": { + "type": "string" + } + } + } + ] + }, + "data_array": { + "description": "Data response in array format.", + "allOf": [ + { + "$ref": "#/definitions/data" + }, + { + "properties": { + "result": { + "type": "array", + "items": { + "type": "number" + } + } + } + } + ] + }, + "data_csvjsonarray": { + "description": "Data response in csvjsonarray format.", + "allOf": [ + { + "$ref": "#/definitions/data" + }, + { + "properties": { + "result": { + "description": "The first inner array contains strings showing the labels of each column, each subsequent array contains the values for each point in time.", + "type": "array", + "items": { + "type": "array", + "items": {} + } + } + } + } + ] + }, + "data_datatable": { + "description": "Data response in datatable / datasource formats (suitable for Google Charts).", + "allOf": [ + { + "$ref": "#/definitions/data" + }, + { + "properties": { + "result": { + "type": "object", + "properties": { + "cols": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "description": "Always empty - for future use." + }, + "label": { + "description": "The dimension returned from the chart." + }, + "pattern": { + "description": "Always empty - for future use." + }, + "type": { + "description": "The type of data in the column / chart-dimension." + }, + "p": { + "description": "Contains any annotations for the column." + } + }, + "required": [ + "id", + "label", + "pattern", + "type" + ] + } + }, + "rows": { + "type": "array", + "items": { + "type": "object", + "properties": { + "c": { + "type": "array", + "items": { + "properties": { + "v": { + "description": "Each value in the row is represented by an object named `c` with five v fields: data, null, null, 0, the value. This format is fixed by the Google Charts API." + } + } + } + } + } + } + } + } + } + } + } + ] + }, "alarms": { "type": "object", "properties": { @@ -1259,7 +1423,7 @@ }, "name": { "type": "string", - "description": "Full alarm name" + "description": "Full alarm name." }, "chart": { "type": "string" @@ -1269,7 +1433,7 @@ }, "active": { "type": "boolean", - "description": "Will be false only if the alarm is disabled in the configuration" + "description": "Will be false only if the alarm is disabled in the configuration." }, "disabled": { "type": "boolean", @@ -1524,4 +1688,4 @@ } } } -}
\ No newline at end of file +} |