web/netdata-swagger.yaml

   1 swagger: '2.0'
   2 info:
   3   title: NetData API
   4   description: 'Real time data collection and graphs...'
   5   version: 1.0.0
   6 host: netdata.firehol.org
   7 schemes:
   8   - http
   9 basePath: /api/v1
  10 produces:
  11   - application/json
  12 paths:
  13   /charts:
  14     get:
  15       summary: 'Get a list of all charts available at the server'
  16       description: 'The charts endpoint returns a summary about all charts stored in the netdata server.'
  17       responses:
  18         '200':
  19           description: 'An array of charts'
  20           schema:
  21             type: array
  22             items:
  23               $ref: '#/definitions/chart_summary'
  24   /chart:
  25     get:
  26       summary: 'Get info about a specific chart'
  27       description: 'The Chart endpoint returns detailed information about a chart.'
  28       parameters:
  29         - name: chart
  30           in: query
  31           description: 'The id of the chart as returned by the /charts call.'
  32           required: true
  33           type: string
  34           format: 'as returned by /charts'
  35           default: 'system.cpu'
  36       responses:
  37         '200':
  38           description: 'A javascript object with detailed information about the chart.'
  39           schema:
  40             $ref: '#/definitions/chart'
  41         '404':
  42           description: 'No chart with the given id is found.'
  43   /data:
  44     get:
  45       summary: 'Get collected data for a specific chart'
  46       description: |
  47         The Data endpoint returns data stored in the round robin database of a chart.
  48       parameters:
  49         - name: chart
  50           in: query
  51           description: 'The id of the chart as returned by the /charts call.'
  52           required: true
  53           type: string
  54           format: 'as returned by /charts'
  55           allowEmptyValue: false
  56           default: system.cpu
  57         - name: dimension
  58           in: query
  59           description: 'zero, one or more dimension ids, as returned by the /chart call.'
  60           required: false
  61           type: array
  62           items:
  63             type: string
  64             collectionFormat: pipes
  65             format: 'as returned by /charts'
  66           allowEmptyValue: false
  67         - name: after
  68           in: query
  69           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.'
  70           required: true
  71           type: number
  72           format: integer
  73           allowEmptyValue: false
  74           default: -600
  75         - name: before
  76           in: query
  77           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.'
  78           required: false
  79           type: number
  80           format: integer
  81           allowEmptyValue: false
  82           default: 0
  83         - name: points
  84           in: query
  85           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.'
  86           required: true
  87           type: number
  88           format: integer
  89           allowEmptyValue: false
  90           default: 20
  91         - name: group
  92           in: query
  93           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).'
  94           required: true
  95           type: string
  96           enum: [ 'max', 'average' ]
  97           default: 'average'
  98           allowEmptyValue: false
  99         - name: format
 100           in: query
 101           description: 'The format of the data to be returned.'
 102           required: true
 103           type: string
 104           enum: [ 'json', 'jsonp', 'csv', 'tsv', 'tsv-excel', 'ssv', 'ssvcomma', 'datatable', 'datasource', 'html', 'array', 'csvjsonarray' ]
 105           default: json
 106           allowEmptyValue: false
 107         - name: options
 108           in: query
 109           description: 'Options that affect data generation.'
 110           required: false
 111           type: array
 112           items:
 113             type: string
 114             enum: [ 'nonzero', 'flip', 'jsonwrap', 'min2max', 'seconds', 'milliseconds', 'abs', 'absolute', 'absolute-sum', 'null2zero', 'objectrows', 'google_json', 'percentage' ]
 115             collectionFormat: pipes
 116           default: seconds|jsonwrap
 117           allowEmptyValue: false
 118         - name: callback
 119           in: query
 120           description: 'For JSONP responses, the callback function name.'
 121           required: false
 122           type: string
 123           allowEmptyValue: true
 124         - name: filename
 125           in: query
 126           description: 'Add Content-Disposition: attachment; filename=<filename> header to the response, that will instruct the browser to save the response with the given filename.'
 127           required: false
 128           type: string
 129           allowEmptyValue: true
 130         - name: tqx
 131           in: query
 132           description: '[Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter.'
 133           required: false
 134           type: string
 135           allowEmptyValue: true
 136       responses:
 137         '200':
 138           description: 'The call was successful. The response should include the data.'
 139           schema:
 140             $ref: '#/definitions/chart'
 141         '400':
 142           description: 'Bad request - the body will include a message stating what is wrong.'
 143         '404':
 144           description: 'No chart with the given id is found.'
 145         '500':
 146           description: 'Internal server error. This usually means the server is out of memory.'
 147 definitions:
 148   chart_summary:
 149     type: object
 150     properties:
 151       hostname:
 152         type: string
 153         description: 'The hostname of the netdata server.'
 154       update_every:
 155         type: number
 156         description: 'The default update frequency of the netdata server. All charts have an update frequency equal or bigger than this.'
 157       charts:
 158         type: object
 159         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.'
 160         properties:
 161           key:
 162               $ref: '#/definitions/chart'
 163   chart:
 164     type: object
 165     properties:
 166       id:
 167         type: string
 168         description: 'The unique id of the chart'
 169       name:
 170         type: string
 171         description: 'The name of the chart'
 172       type:
 173         type: string
 174         description: 'The type of the chart. Types are not handled by netdata. You can use this field for anything you like.'
 175       family:
 176         type: string
 177         description: 'The family of the chart. Families are not handled by netdata. You can use this field for anything you like.'
 178       title:
 179         type: string
 180         description: 'The title of the chart.'
 181       priority:
 182         type: string
 183         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.'
 184       enabled:
 185         type: boolean
 186         description: 'True when the chart is enabled. Disabled charts do not currently collect values, but they may have historical values available.'
 187       units:
 188         type: string
 189         description: 'The unit of measurement for the values of all dimensions of the chart.'
 190       data_url:
 191         type: string
 192         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.'
 193       chart_type:
 194         type: string
 195         description: 'The chart type.'
 196         enum: [ 'line', 'area', 'stacked' ]
 197       duration:
 198         type: number
 199         description: 'The duration, in seconds, of the round robin database maintained by netdata.'
 200       first_entry:
 201         type: number
 202         description: 'The UNIX timestamp of the first entry (the oldest) in the round robin database.'
 203       last_entry:
 204         type: number
 205         description: 'The UNIX timestamp of the latest entry in the round robin database.'
 206       update_every:
 207         type: number
 208         description: 'The update frequency of this chart, in seconds. One value every this amount of time is kept in the round robin database.'
 209       dimensions:
 210         description: 'The dimensions of the chart.'
 211         type: object
 212         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.'
 213         properties:
 214           key:
 215               $ref: '#/definitions/dimension'
 216   dimension:
 217     type: object
 218     properties:
 219       name:
 220         type: string
 221         description: 'The name of the dimension'
 222
 223   json_wrap:
 224     type: object
 225     properties:
 226       api:
 227         type: number
 228         description: 'The API version this conforms to, currently 1'
 229       id:
 230         type: string
 231         description: 'The unique id of the chart'
 232       name:
 233         type: string
 234         description: 'The name of the chart'
 235       update_every:
 236         type: number
 237         description: 'The update frequency of this chart, in seconds. One value every this amount of time is kept in the round robin database (indepedently of the current view).'
 238       view_update_every:
 239         type: number
 240         description: 'The current view appropriate update frequency of this chart, in seconds. There is no point to request chart refreshes, using the same settings, more frequently than this.'
 241       first_entry:
 242         type: number
 243         description: 'The UNIX timestamp of the first entry (the oldest) in the round robin database (indepedently of the current view).'
 244       last_entry:
 245         type: number
 246         description: 'The UNIX timestamp of the latest entry in the round robin database (indepedently of the current view).'
 247       after:
 248         type: number
 249         description: 'The UNIX timestamp of the first entry (the oldest) returned in this response.'
 250       before:
 251         type: number
 252         description: 'The UNIX timestamp of the latest entry returned in this response.'
 253       min:
 254         type: number
 255         description: 'The minimum value returned in the current view. This can be used to size the y-series of the chart.'
 256       max:
 257         type: number
 258         description: 'The maximum value returned in the current view. This can be used to size the y-series of the chart.'
 259       dimension_names:
 260         description: 'The dimension names of the chart as returned in the current view.'
 261         type: array
 262         items:
 263           type: string
 264       dimension_ids:
 265         description: 'The dimension IDs of the chart as returned in the current view.'
 266         type: array
 267         items:
 268           type: string
 269       latest_values:
 270         description: 'The latest values collected for the chart (indepedently of the current view).'
 271         type: array
 272         items:
 273           type: string
 274       view_latest_values:
 275         description: 'The latest values returned with this response.'
 276         type: array
 277         items:
 278           type: string
 279       dimensions:
 280         type: number
 281         description: 'The number of dimensions returned.'
 282       points:
 283         type: number
 284         description: 'The number of rows / points returned.'
 285       format:
 286         type: string
 287         description: 'The format of the result returned.'
 288       result:
 289         description: 'The result requested, in the format requested.'