web/netdata-swagger.yaml

   1 swagger: '2.0'
   2 info:
   3   title: NetData API
   4   description: 'Real time monitoring for linux, over the web!'
   5   version: 1.0.0
   6 schemes:
   7   - http
   8 basePath: /api/v1
   9 produces:
  10   - application/json
  11 paths:
  12   /charts:
  13     get:
  14       summary: 'Get a list of all charts available at the server'
  15       description: 'The charts endpoint returns a summary about all charts stored in the netdata server.'
  16       responses:
  17         '200':
  18           description: 'An array of charts'
  19           schema:
  20             type: array
  21             items:
  22               $ref: '#/definitions/chart_summary'
  23   /chart:
  24     get:
  25       summary: 'Get info about a specific chart'
  26       description: 'The Chart endpoint returns detailed information about a chart.'
  27       parameters:
  28         - name: chart
  29           in: query
  30           description: 'The id of the chart as returned by the /charts call.'
  31           required: true
  32           type: string
  33           format: 'as returned by /charts'
  34       responses:
  35         '200':
  36           description: 'A javascript object with detailed information about the chart.'
  37           schema:
  38             $ref: '#/definitions/chart'
  39         '404':
  40           description: 'No chart with the given id is found.'
  41   /data:
  42     get:
  43       summary: 'Get collected data for a specific chart'
  44       description: |
  45         The Data endpoint returns data stored in the round robin database of a chart.
  46       parameters:
  47         - name: chart
  48           in: query
  49           description: 'The id of the chart as returned by the /charts call.'
  50           required: true
  51           type: string
  52           format: 'as returned by /charts'
  53           allowEmptyValue: false
  54         - name: dimension
  55           in: query
  56           description: 'zero, one or more dimension ids, as returned by the /chart call.'
  57           required: false
  58           type: array
  59           items:
  60             type: string
  61             collectionFormat: pipes
  62             format: 'as returned by /charts'
  63           allowEmptyValue: false
  64         - name: after
  65           in: query
  66           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.'
  67           required: true
  68           type: number
  69           format: integer
  70           allowEmptyValue: false
  71           default: -600
  72         - name: before
  73           in: query
  74           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.'
  75           required: false
  76           type: number
  77           format: integer
  78           allowEmptyValue: false
  79           default: 0
  80         - name: points
  81           in: query
  82           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 are returned.'
  83           required: true
  84           type: number
  85           format: integer
  86           allowEmptyValue: false
  87           default: 100
  88         - name: group
  89           in: query
  90           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. Two methods are supported, "max" and "average". "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).'
  91           required: true
  92           type: string
  93           enum: [ 'max', 'average' ]
  94           default: 'max'
  95           allowEmptyValue: false
  96         - name: format
  97           in: query
  98           description: 'The format of the data to be returned.'
  99           required: true
 100           type: string
 101           enum: [ 'json', 'jsonp', 'csv', 'tsv', 'tsv-excel', 'ssv', 'ssvcomma', 'datatable', 'datasource', 'html', 'array' ]
 102           default: json
 103           allowEmptyValue: false
 104         - name: options
 105           in: query
 106           description: 'Options that affect data generation.'
 107           required: false
 108           type: array
 109           items:
 110             type: string
 111             enum: [ 'nonzero', 'flip', 'jsonwrap', 'min2max', 'seconds', 'milliseconds', 'abs', 'absolute', 'absolute-sum', 'null2zero', 'objectrows', 'google_json' ]
 112             collectionFormat: pipes
 113             format: ''
 114           allowEmptyValue: false
 115         - name: tqx
 116           in: query
 117           description: '[Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter.'
 118           required: false
 119           type: string
 120           allowEmptyValue: false
 121       responses:
 122         '200':
 123           description: 'The call was successful. The response should include the data.'
 124           schema:
 125             $ref: '#/definitions/chart'
 126         '400':
 127           description: 'Bad request - the body will include a message stating what is wrong.'
 128         '404':
 129           description: 'No chart with the given id is found.'
 130         '500':
 131           description: 'Internal server error. This usually means the server is out of memory.'
 132 definitions:
 133   chart_summary:
 134     type: object
 135     properties:
 136       hostname:
 137         type: string
 138         description: 'The hostname of the netdata server.'
 139       update_every:
 140         type: number
 141         description: 'The default update frequency of the netdata server. All charts have an update frequency equal or bigger than this.'
 142       charts:
 143         type: object
 144         description: 'An object containing all the chart objects available at the netdata server. This is used as an indexed array. The key of each chart object is the id of the chart.'
 145         properties:
 146           key:
 147               $ref: '#/definitions/chart'
 148   chart:
 149     type: object
 150     properties:
 151       id:
 152         type: string
 153         description: 'The unique id of the chart'
 154       name:
 155         type: string
 156         description: 'The name of the chart'
 157       type:
 158         type: string
 159         description: 'The type of the chart. Types are not handled by netdata. You can use this field for anything you like.'
 160       family:
 161         type: string
 162         description: 'The family of the chart. Families are not handled by netdata. You can use this field for anything you like.'
 163       title:
 164         type: string
 165         description: 'The title of the chart.'
 166       priority:
 167         type: string
 168         description: 'The relative priority of the chart. NetData does not care about priorities. This is just an indication of importance for the chart viewers to sort charts of higher priority (lower number) closer to the top. Priority sorting should only be used among charts of the same type or family.'
 169       enabled:
 170         type: boolean
 171         description: 'True when the chart is enabled. Disabled charts do not currently collect values, but they may have historical values available.'
 172       units:
 173         type: string
 174         description: 'The unit of measurement for the values of all dimensions of the chart.'
 175       data_url:
 176         type: string
 177         description: 'The absolute path to get data values for this chart. You are expected to use this path as the base when constructing the URL to fetch data values for this chart.'
 178       chart_type:
 179         type: string
 180         description: 'The chart type.'
 181         enum: [ 'line', 'area', 'stacked' ]
 182       duration:
 183         type: number
 184         description: 'The duration, in seconds, of the round robin database maintained by netdata.'
 185       first_entry:
 186         type: number
 187         description: 'The UNIX timestamp of the first entry (the oldest) in the round robin database.'
 188       last_entry:
 189         type: number
 190         description: 'The UNIX timestamp of the latest entry in the round robin database.'
 191       update_every:
 192         type: number
 193         description: 'The update frequency of this chart, in seconds. One value every this amount of time is kept in the round robin database.'
 194       dimensions:
 195         description: 'The dimensions of the chart.'
 196         type: object
 197         description: 'An object containing all the chart dimensions available for the chart. This is used as an indexed array. The key of the object the id of the dimension.'
 198         properties:
 199           key:
 200               $ref: '#/definitions/dimension'
 201   dimension:
 202     type: object
 203     properties:
 204       name:
 205         type: string
 206         description: 'The name of the dimension'
 207