diff options
Diffstat (limited to 'web/api/netdata-swagger.yaml')
| -rw-r--r-- | web/api/netdata-swagger.yaml | 2049 |
1 files changed, 1124 insertions, 925 deletions
diff --git a/web/api/netdata-swagger.yaml b/web/api/netdata-swagger.yaml index 76a2a2f1a5..78644a76a8 100644 --- a/web/api/netdata-swagger.yaml +++ b/web/api/netdata-swagger.yaml @@ -1,15 +1,8 @@ -swagger: '2.0' +openapi: 3.0.0 info: title: NetData API description: Real-time performance and health monitoring. version: 1.11.1_rolling -host: registry.my-netdata.io -schemes: - - https - - http -basePath: /api/v1 -produces: - - application/json paths: /info: get: @@ -26,21 +19,26 @@ paths: * number of alarms in warning state * number of alarms in critical state responses: - '200': + "200": description: netdata basic information. - schema: - $ref: '#/definitions/info' - '503': + content: + application/json: + schema: + $ref: "#/components/schemas/info" + "503": description: netdata daemon not ready (used for health checks). /charts: get: summary: Get a list of all charts available at the server - description: The charts endpoint returns a summary about all charts stored in the netdata server. + description: The charts endpoint returns a summary about all charts stored in the + netdata server. responses: - '200': + "200": description: An array of charts. - schema: - $ref: '#/definitions/chart_summary' + content: + application/json: + schema: + $ref: "#/components/schemas/chart_summary" /chart: get: summary: Get info about a specific chart @@ -50,190 +48,247 @@ paths: in: query description: The id of the chart as returned by the /charts call. required: true - type: string - format: as returned by /charts - default: system.cpu + schema: + type: string + format: as returned by /charts + default: system.cpu responses: - '200': + "200": description: A javascript object with detailed information about the chart. - schema: - $ref: '#/definitions/chart' - '400': + content: + application/json: + schema: + $ref: "#/components/schemas/chart" + "400": description: No chart id was supplied in the request. - '404': + "404": description: No chart with the given id is found. /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 in: query description: The id of the chart as returned by the /charts call. required: true - type: string - format: as returned by /charts - default: system.cpu - responses: - '200': - description: A javascript object with information about the chart and the available variables. schema: - $ref: '#/definitions/alarm_variables' - '400': + type: string + format: as returned by /charts + default: system.cpu + responses: + "200": + description: A javascript object with information about the chart and the + available variables. + content: + application/json: + schema: + $ref: "#/components/schemas/alarm_variables" + "400": description: Bad request - the body will include a message stating what is wrong. - '404': + "404": description: No chart with the given id is found. - '500': - description: Internal server error. This usually means the server is out of memory. + "500": + description: Internal server error. This usually means the server is out of + memory. /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. + description: The data endpoint returns data stored in the round robin database of a + chart. parameters: - name: chart in: query description: The id of the chart as returned by the /charts call. required: true - type: string - format: as returned by /charts allowEmptyValue: false - default: system.cpu + schema: + type: string + format: as returned by /charts + default: system.cpu - 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: - type: string - collectionFormat: pipes - format: as returned by /charts allowEmptyValue: false + schema: + type: array + items: + type: string + format: as returned by /charts - name: after in: query - description: 'This parameter can either be an absolute timestamp specifying the starting point of the data to be returned, or a relative number of seconds (negative, relative to parameter: before). Netdata will assume it is a relative number if it is less that 3 years (in seconds). Netdata will adapt this parameter to the boundaries of the round robin database. The default is the beginning of the round robin database (i.e. by default netdata will attempt to return data for the entire database).' + description: "This parameter can either be an absolute timestamp specifying the + starting point of the data to be returned, or a relative number of + seconds (negative, relative to parameter: before). Netdata will + assume it is a relative number if it is less that 3 years (in + seconds). Netdata will adapt this parameter to the boundaries of the + round robin database. The default is the beginning of the round + robin database (i.e. by default netdata will attempt to return data + for the entire database)." required: true - type: number - format: integer allowEmptyValue: false - default: -600 + schema: + type: number + format: integer + default: -600 - name: before in: query - description: 'This parameter can either be an absolute timestamp specifying the ending point of the data to be returned, or a relative number of seconds (negative), relative to the last collected timestamp. Netdata will assume it is a relative number if it is less than 3 years (in seconds). Netdata will adapt this parameter to the boundaries of the round robin database. The default is zero (i.e. the timestamp of the last value collected).' + description: This parameter can either be an absolute timestamp specifying the + ending point of the data to be returned, or a relative number of + seconds (negative), relative to the last collected timestamp. + Netdata will assume it is a relative number if it is less than 3 + years (in seconds). Netdata will adapt this parameter to the + boundaries of the round robin database. The default is zero (i.e. + the timestamp of the last value collected). required: false - type: number - format: integer - default: 0 + schema: + type: number + format: integer + default: 0 - name: points in: query - description: 'The number of points to be returned. If not given, or it is <= 0, or it is bigger than the points stored in the round robin database for this chart for the given duration, all the available collected values for the given duration will be returned.' + description: The number of points to be returned. If not given, or it is <= 0, or + it is bigger than the points stored in the round robin database for + this chart for the given duration, all the available collected + values for the given duration will be returned. required: true - type: number - format: integer allowEmptyValue: false - default: 20 + schema: + type: number + format: integer + default: 20 - name: group in: query - description: 'The grouping method. If multiple collected values are to be grouped in order to return fewer points, this parameters defines the method of grouping. methods supported "min", "max", "average", "sum", "incremental-sum". "max" is actually calculated on the absolute value collected (so it works for both positive and negative dimesions to return the most extreme value in either direction).' + description: The grouping method. If multiple collected values are to be grouped + in order to return fewer points, this parameters defines the method + of grouping. methods supported "min", "max", "average", "sum", + "incremental-sum". "max" is actually calculated on the absolute + value collected (so it works for both positive and negative + dimesions to return the most extreme value in either direction). required: true - type: string - enum: - - min - - max - - average - - median - - stddev - - sum - - incremental-sum - default: average allowEmptyValue: false + schema: + type: string + enum: + - min + - max + - average + - median + - stddev + - sum + - incremental-sum + default: average - name: gtime in: query - description: 'The grouping number of seconds. This is used in conjunction with group=average to change the units of metrics (ie when the data is per-second, setting gtime=60 will turn them to per-minute).' + description: The grouping number of seconds. This is used in conjunction with + group=average to change the units of metrics (ie when the data is + per-second, setting gtime=60 will turn them to per-minute). required: false - type: number - format: integer allowEmptyValue: false - default: 0 + schema: + type: number + format: integer + default: 0 - name: format in: query description: The format of the data to be returned. required: true - type: string - enum: - - json - - jsonp - - csv - - tsv - - tsv-excel - - ssv - - ssvcomma - - datatable - - datasource - - html - - markdown - - array - - csvjsonarray - default: json allowEmptyValue: false + schema: + type: string + enum: + - json + - jsonp + - csv + - tsv + - tsv-excel + - ssv + - ssvcomma + - datatable + - datasource + - html + - markdown + - array + - csvjsonarray + default: json - name: options in: query description: Options that affect data generation. required: false - type: array - items: - type: string - enum: - - nonzero - - flip - - jsonwrap - - min2max - - seconds - - milliseconds - - abs - - absolute - - absolute-sum - - null2zero - - objectrows - - google_json - - percentage - - unaligned - - match-ids - - match-names - - showcustomvars - collectionFormat: pipes - default: - - seconds - - jsonwrap allowEmptyValue: false + schema: + type: array + items: + type: string + enum: + - nonzero + - flip + - jsonwrap + - min2max + - seconds + - milliseconds + - abs + - absolute + - absolute-sum + - null2zero + - objectrows + - google_json + - percentage + - unaligned + - match-ids + - match-names + - showcustomvars + default: + - seconds + - jsonwrap - name: callback in: query - description: 'For JSONP responses, the callback function name.' + description: For JSONP responses, the callback function name. required: false - type: string allowEmptyValue: true + schema: + type: string - name: filename in: query - description: 'Add Content-Disposition: attachment; filename=<filename> header to the response, that will instruct the browser to save the response with the given filename.' + description: "Add Content-Disposition: attachment; filename= header to + the response, that will instruct the browser to save the response + with the given filename." required: false - type: string allowEmptyValue: true + schema: + type: string - name: tqx in: query - description: '[Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter.' + description: "[Google Visualization + API](https://developers.google.com/chart/interactive/docs/dev/imple\ + menting_data_source?hl=en) formatted parameter." required: false - type: string allowEmptyValue: true - responses: - '200': - 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/data' - '400': + type: string + responses: + "200": + 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. + content: + application/json: + schema: + $ref: "#/components/schemas/data" + "400": description: Bad request - the body will include a message stating what is wrong. - '404': + "404": description: No chart with the given id is found. - '500': - description: Internal server error. This usually means the server is out of memory. + "500": + description: Internal server error. This usually means the server is out of + memory. /badge.svg: get: summary: Generate a SVG image for a chart (or dimension) @@ -243,973 +298,1117 @@ paths: in: query description: The id of the chart as returned by the /charts call. required: true - type: string - format: as returned by /charts allowEmptyValue: false - default: system.cpu + schema: + type: string + format: as returned by /charts + default: system.cpu - name: alarm in: query description: The name of an alarm linked to the chart. required: false - type: string - format: any text allowEmptyValue: true + schema: + type: string + format: any text - 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: - type: string - collectionFormat: pipes - format: as returned by /charts allowEmptyValue: false + schema: + type: array + items: + type: string + format: as returned by /charts - name: after in: query - description: 'This parameter can either be an absolute timestamp specifying the starting point of the data to be returned, or a relative number of seconds, to the last collected timestamp. Netdata will assume it is a relative number if it is smaller than the duration of the round robin database for this chart. So, if the round robin database is 3600 seconds, any value from -3600 to 3600 will trigger relative arithmetics. Netdata will adapt this parameter to the boundaries of the round robin database.' + description: This parameter can either be an absolute timestamp specifying the + starting point of the data to be returned, or a relative number of + seconds, to the last collected timestamp. Netdata will assume it is + a relative number if it is smaller than the duration of the round + robin database for this chart. So, if the round robin database is + 3600 seconds, any value from -3600 to 3600 will trigger relative + arithmetics. Netdata will adapt this parameter to the boundaries of + the round robin database. required: true - type: number - format: integer allowEmptyValue: false - default: -600 + schema: + type: number + format: integer + default: -600 - name: before in: query - description: 'This parameter can either be an absolute timestamp specifying the ending point of the data to be returned, or a relative number of seconds, to the last collected timestamp. Netdata will assume it is a relative number if it is smaller than the duration of the round robin database for this chart. So, if the round robin database is 3600 seconds, any value from -3600 to 3600 will trigger relative arithmetics. Netdata will adapt this parameter to the boundaries of the round robin database.' + description: This parameter can either be an absolute timestamp specifying the + ending point of the data to be returned, or a relative number of + seconds, to the last collected timestamp. Netdata will assume it is + a relative number if it is smaller than the duration of the round + robin database for this chart. So, if the round robin database is + 3600 seconds, any value from -3600 to 3600 will trigger relative + arithmetics. Netdata will adapt this parameter to the boundaries of + the round robin database. required: false - type: number - format: integer - default: 0 + schema: + type: number + format: integer + default: 0 - name: group in: query - description: 'The grouping method. If multiple collected values are to be grouped in order to return fewer points, this parameters defines the method of grouping. methods are supported "min", "max", "average", "sum", "incremental-sum". "max" is actually calculated on the absolute value collected (so it works for both positive and negative dimesions to return the most extreme value in either direction).' + description: The grouping method. If multiple collected values are to be grouped + in order to return fewer points, this parameters defines the method + of grouping. methods are supported "min", "max", "average", "sum", + "incremental-sum". "max" is actually calculated on the absolute + value collected (so it works for both positive and negative + dimesions to return the most extreme value in either direction). required: true - type: string - enum: - - min - - max - - average - - median - - stddev - - sum - - incremental-sum - default: average allowEmptyValue: false + schema: + type: string + enum: + - min + - max + - average + - median + - stddev + - sum + - incremental-sum + default: average - name: options in: query description: Options that affect data generation. required: false - type: array - items: - type: string - enum: - - abs - - absolute - - display-absolute - - absolute-sum - - null2zero - - percentage - - unaligned - collectionFormat: pipes - default: - - absolute allowEmptyValue: true + schema: + type: array + items: + type: string + enum: + - abs + - absolute + - display-absolute + - absolute-sum + - null2zero + - percentage + - unaligned + default: + - absolute - name: label in: query description: A text to be used as the label. required: false - type: string - format: any text allowEmptyValue: true + schema: + type: string + format: any text - name: units in: query description: A text to be used as the units. required: false - type: string - format: any text allowEmptyValue: true + schema: + type: string + format: any text - name: label_color in: query description: A color to be used for the background of the label. required: false - type: string - format: any text allowEmptyValue: true + schema: + type: string + format: any text - 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: + colorvalue|color:null The following operators are + supported: >, <, >=, <=, =, :null (to check if no value exists)." required: false - type: string - format: any text allowEmptyValue: true + schema: + type: string + format: any text - 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 allowEmptyValue: true + schema: + type: number + format: integer - 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 allowEmptyValue: true + schema: + type: number + format: integer - name: scale in: query description: Set the scale of the badge (greater or equal to 100). required: false - type: number - format: integer allowEmptyValue: true + schema: + type: number + format: integer responses: - '200': + "200": description: The call was successful. The response should be an SVG image. - '400': + "400": description: Bad request - the body will include a message stating what is wrong. - '404': + "404": description: No chart with the given id is found. - '500': - description: Internal server error. This usually means the server is out of memory. + "500": + description: Internal server error. This usually means the server is out of + memory. /allmetrics: get: summary: Get a value of all the metrics maintained by netdata - description: The allmetrics 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. required: true - type: string - enum: - - shell - - prometheus - - prometheus_all_hosts - - json - default: shell + schema: + type: string + enum: + - shell + - prometheus + - prometheus_all_hosts + - json + default: shell - name: help in: query description: Enable or disable HELP lines in prometheus output. required: false - type: string - enum: - - 'yes' - - 'no' - default: 'no' + schema: + type: string + enum: + - yes + - no + default: no - name: types in: query description: Enable or disable TYPE lines in prometheus output. required: false - type: string - enum: - - 'yes' - - 'no' - default: 'no' + schema: + type: string + enum: + - yes + - no + default: no - name: timestamps in: query description: Enable or disable timestamps in prometheus output. required: false - type: string - enum: - - 'yes' - - 'no' - default: 'yes' + schema: + type: string + enum: + - yes + - no + default: yes - name: names in: query - description: When enabled netdata will report dimension names. When disabled netdata will report dimension IDs. The default is controlled in netdata.conf. + description: When enabled netdata will report dimension names. When disabled + netdata will report dimension IDs. The default is controlled in + netdata.conf. required: false - type: string - enum: - - 'yes' - - 'no' - default: 'yes' + schema: + type: string + enum: + - yes + - no + default: yes - 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: - - 'yes' - - 'no' - default: 'yes' + schema: + type: string + enum: + - yes + - no + default: yes - name: hideunits in: query - description: 'When enabled, netdata will not include the units in the metric names, for the default source=average.' + description: When enabled, netdata will not include the units in the metric + names, for the default source=average. required: false - type: string - enum: - - 'yes' - - 'no' - default: 'yes' + schema: + type: string + enum: + - yes + - no + default: yes - name: server in: query - description: Set a distinct name of the client querying prometheus metrics. Netdata will use the client IP if this is not set. + description: Set a distinct name of the client querying prometheus metrics. + Netdata will use the client IP if this is not set. required: false - type: string - format: any text + schema: + type: string + format: any text - name: prefix in: query description: Prefix all prometheus metrics with this string. required: false - type: string - format: any text + schema: + type: string + format: any text - name: data in: query - description: Select the prometheus response data source. There is a setting in netdata.conf for the default. + description: Select the prometheus response data source. There is a setting in + netdata.conf for the default. required: false - type: string - enum: - - as-collected - - average - - sum - default: average + schema: + type: string + enum: + - as-collected + - average + - sum + default: average responses: - '200': + "200": description: All the metrics returned in the format requested. - '400': + "400": description: The format requested is not supported. /alarms: get: summary: Get a list of active or raised alarms on the server - description: 'The alarms endpoint returns the list of all raised or enabled alarms on the netdata server. Called without any parameters, the raised alarms in state WARNING or CRITICAL are returned. By passing "?all", all the enabled alarms are returned.' + description: The alarms endpoint returns the list of all raised or enabled alarms on + the netdata server. Called without any parameters, the raised alarms in + state WARNING or CRITICAL are returned. By passing "?all", all the + enabled alarms are returned. parameters: - 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 + schema: + type: boolean responses: - '200': + "200": description: An object containing general info and a linked list of alarms. - schema: - $ref: '#/definitions/alarms' + content: + application/json: + schema: + $ref: "#/components/schemas/alarms" /alarm_log: get: summary: Retrieves the entries of the alarm log - description: 'Returns an array of alarm_log entries, with historical information on raised and cleared alarms.' + description: Returns an array of alarm_log entries, with historical information on + raised and cleared alarms. parameters: - 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 + schema: + type: integer responses: - '200': + "200": description: An array of alarm log entries. - schema: - type: array - items: - $ref: '#/definitions/alarm_log_entry' + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/alarm_log_entry" /alarm_count: get: summary: Get an overall status of the chart - description: Checks multiple charts with the same context and counts number of alarms with given status. + description: Checks multiple charts with the same context and counts number of alarms + with given status. parameters: - in: query name: context description: Specify context which should be checked. required: false allowEmptyValue: true - type: array - items: - type: string - collectionFormat: pipes - default: - - system.cpu + schema: + type: array + items: + type: string + default: + - system.cpu - in: query name: status description: Specify alarm status to count. required: false allowEmptyValue: true - type: string - enum: - - REMOVED - - UNDEFINED - - UNINITIALIZED - - CLEAR - - RAISED - - WARNING - - CRITICAL - default: RAISED - responses: - '200': - description: An object containing a count of alarms with given |