Skip to content
This repository has been archived by the owner on Jan 19, 2022. It is now read-only.

API

Jump to bottom
obfuscurity edited this page May 15, 2013 · 27 revisions

The Descartes API is RESTful. It's designed to have predictable, resource-oriented URLS, to use HTTP response codes to indicate API errors, and to use built-in HTTP features which can be understood by off-the-shelf HTTP clients. JSON will be returned in all successful responses (except 204 No Content) from the API.

Versioning

There is currently no versioning support within Descartes. This is expected to change although no timetable has been set.

Authentication

Authentication for browser-based clients should use one of our approved OAuth mechanisms (currently Google or GitHub). Programmatic clients may alternatively use a more traditional (read: less secure) token string for authentication. Descartes currently only supports the use of a server-side API_TOKEN environment variable holding the authentication token. Because this token is not tied to a specific user, any resources created using this method will store api@localhost as the owner attribute.

In the future we expect to support a more elaborate token management system associated with actual users.

  • X-DESCARTES-API-TOKEN - Client HTTP request header used to pass the simple authentication token.

HTTP Status Code Summary

  • 200 - OK - Request succeeded.

  • 201 - Created - Resource created and returned.

  • 204 - No Content - Action successfully completed but no data returned (typically after a DELETE).

  • 400 - Bad Request - Missing or incorrect parameters.

  • 401 - Unauthorized - Authentication failed (user authentication) or missing (API token).

  • 404 - Resource Not Found - The requested Site or User resource was not found.

Routes

Requests against the Descartes API must set the Accept header to application/json and should always return a valid HTTP status code.

HTTP/1.1 200 OK
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
Content-Type: application/json;charset=utf-8
Content-Length: 10599
Connection: keep-alive
Server: thin 1.2.10 codename Im dumb

Graphs

List Graphs

$ curl -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -X GET http://127.0.0.1:5000/graphs

[
  {
    "json_class": "Graph",
    "id": 11,
    "uuid": "225d73e4154dc0fa35c6d3cfd1a685fe",
    "owner": "[email protected]",
    "name": "Interface_eth0_packets",
    "description": null,
    "url": "http://graphite.example.com/render/?width=586&height=308&_salt=1341964392.466&target=graphite-example-com.interface.if_packets-eth0.*&name=Interface_eth0_packets",
    "configuration": "{'width':'586','height':'308','_salt':'1341964392.466','target':['graphite-example-com.interface.if_packets-eth0.*'],'name':'Interface_eth0_packets'}",
    "overrides": null,
    "enabled": true,
    "created_at": "2013-03-11 20:04:35 -0400",
    "updated_at": "2013-03-13 00:30:02 -0400",
    "views": 40
  }
]

New Graph

Creating a new graph resource requires a Graphite-compatible encoded URL as the node parameter in a POST request. Optionally you may also pass a name and one or more tag parameters.

$ curl -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' -d 'name=My New Graph' -d 'tag=foo' \
  --data-urlencode 'node=https://graphite.example.com/render/?target=carbon.agents.li520-115-a.metricsReceived' \
  -X POST http://127.0.0.1:5000/graphs

{
  "json_class": "Graph",
  "id": 15,
  "uuid": "004f0ffa5334f74f863385ed230a6fb0",
  "owner": "api@localhost",
  "name": "Please name me",
  "description": null,
  "url": "https://graphite.example.com/render/?target=carbon.agents.li520-115-a.metricsReceived",
  "configuration": "{'target':['carbon.agents.li520-115-a.metricsReceived']}",
  "overrides": null,
  "enabled": true,
  "created_at": "2013-03-13 16:36:10 -0400",
  "updated_at": "2013-03-13 16:36:10 -0400",
  "views": 0
}

Show Graph

$ curl -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -X GET http://127.0.0.1:5000/graphs/f9196b5f7760c37863588be3b9ff9bc7

{
  "json_class": "Graph",
  "id": 20,
  "uuid": "f9196b5f7760c37863588be3b9ff9bc7",
  "owner": "api@localhost",
  "name": "My New Graph",
  "description": null,
  "url": "https://graphite.example.com/render/?target=carbon.agents.li520-115-a.metricsReceived",
  "configuration": "{'target':['carbon.agents.li520-115-a.metricsReceived']}",
  "overrides": null,
  "enabled": true,
  "created_at": "2013-03-13 17:07:15 -0400",
  "updated_at": "2013-03-13 17:07:15 -0400",
  "views": 0
}

Edit Graph

Changes to a graph resource should generally be isolated to the name and description attributes, and the overrides object for any graph configuration modifications.

The overrides object is currently only used within Descartes for graph-level configuration (e.g. lineMode, areaMode, etc). In the future, once target-level configuration is exposed in the UI, these settings will also be stored in the overrides object. However, for future compatibility, it's recommended to avoid using this for anything beyond the current set of supported UI features.

The overrides object will be saved with exactly the attributes that are sent to the API. Therefore, it's important to note if data exists in that column (via Show Graph) and resubmit all of the data, with your changes applied.

$ curl -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -d 'overrides={"lineMode":"slope","areaMode":"all","logBase":"off","drawNullAsZero":"off"}' \
  -X PUT http://127.0.0.1:5000/graphs/4af66399da295a73f378edce87cc1a23

{
  "json_class": "Graph",
  "id": 10,
  "uuid": "4af66399da295a73f378edce87cc1a23",
  "owner": "[email protected]",
  "name": "Interface_eth0_octets",
  "description": null,
  "url": "http://graphite.example.com/render/?width=586&height=308&_salt=1341964357.613&target=graphite-example-com.interface.if_octets-eth0.*&name=Interface_eth0_octets",
  "configuration": "{'width':'586','height':'308','_salt':'1341964357.613','target':['graphite-example-com.interface.if_octets-eth0.*'],'name':'Interface_eth0_octets'}",
  "overrides": "{'lineMode':'slope','areaMode':'all','logBase':'off','drawNullAsZero':'off'}",
  "enabled": true,
  "created_at": "2013-03-11 20:04:35 -0400",
  "updated_at": "2013-03-13 21:10:45 -0400",
  "views": 1
}

List Tags for a Graph

$ curl -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -X GET http://127.0.0.1:5000/graphs/4af66399da295a73f378edce87cc1a23/tags

[
  {
    "json_class": "Tag",
    "id": 6,
    "name": "foo"
  }
]

Add a Tag to a Graph

$ curl -i -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' -d 'name=bar' \
  -X POST http://127.0.0.1:5000/graphs/4af66399da295a73f378edce87cc1a23/tags

HTTP/1.1 204 No Content
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
Connection: close
Server: thin 1.2.10 codename Im dumb

Delete a Tag from a Graph

$ curl -i -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -X DELETE http://127.0.0.1:5000/graphs/4af66399da295a73f378edce87cc1a23/tags/7

HTTP/1.1 204 No Content
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
Connection: close
Server: thin 1.2.10 codename Im dumb

Delete Graph

A successful request to DELETE a graph resource should return a 204 No Content response. If the deleted resource was also the last remaining graph in a dashboard, that dashboard will be removed as well.

$ curl -i -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -X DELETE http://127.0.0.1:5000/graphs/f09e3b3c18a3cda3a49aa8bf2cc5fc26

HTTP/1.1 204 No Content
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
Connection: close
Server: thin 1.2.10 codename Im dumb

Search Graphs

Passing the search param with a search string will return an array of all graphs containing that string in its name or any tags associated with that graph.

$ curl -s -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' -d 'search=disk' \
  -X GET http://127.0.0.1:5000/graphs

[
  {
    "json_class": "Graph",
    "id": 8,
    "uuid": "61a13556f7425d3eaed3bbed5aa3faf2",
    "owner": "[email protected]",
    "name": "Disk_xvda_writes",
    "description": null,
    "url": "http://graphite.example.com/render/?width=586&height=308&_salt=1341718940.421&from=-1hours&target=alias(graphite-example-com.disk-xvda.disk_merged.write%2C%22xvda%20merged%20write%22)&target=alias(secondYAxis(graphite-example-com.disk-xvda.disk_octets.write)%2C%22xvda%20octets%20write%22)&target=alias(graphite-example-com.disk-xvda.disk_ops.write%2C%22xvda%20ops%20write%22)&target=alias(graphite-example-com.disk-xvda.disk_time.write%2C%22xvda%20time%20write%22)&title=Disk_xvda_writes&name=Disk_xvda_writes",
    "configuration": "{'width':'586','height':'308','_salt':'1341718940.421','from':'-1hours','target':['alias(graphite-example-com.disk-xvda.disk_merged.write,'xvda merged write')','alias(secondYAxis(graphite-example-com.disk-xvda.disk_octets.write),'xvda octets write')','alias(graphite-example-com.disk-xvda.disk_ops.write,'xvda ops write')','alias(graphite-example-com.disk-xvda.disk_time.write,'xvda time write')'],'title':'Disk_xvda_writes','name':'Disk_xvda_writes'}",
    "overrides": null,
    "enabled": true,
    "created_at": "2013-03-11 20:04:34 -0400",
    "updated_at": "2013-03-11 20:04:34 -0400",
    "views": 0
  }
]

Dashboards

List Dashboards

$ curl -s -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -X GET http://127.0.0.1:5000/dashboards

[
  {
    "json_class": "Dashboard",
    "id": 1,
    "uuid": "6a40ae3af465f4e58f9135c7b7fde854",
    "owner": "[email protected]",
    "name": "Disk activity",
    "description": null,
    "configuration": null,
    "enabled": true,
    "created_at": "2013-03-13 18:33:52 -0400",
    "updated_at": "2013-03-13 18:33:52 -0400",
    "graph_count": 2
  }
]

New Dashboard

Creating a new dashboard resource requires a name and one or more comma-delimited graph uuids passed in the uuids parameter of a POST request.

$ curl -s -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -d 'name=My New Dashboard' -d 'uuids=4af66399da295a73f378edce87cc1a23,225d73e4154dc0fa35c6d3cfd1a685fe' \
  -X POST http://127.0.0.1:5000/dashboards

{
  "json_class": "Dashboard",
  "id": 2,
  "uuid": "83aa7d665215dd233abc2850b6025af4",
  "owner": "api@localhost",
  "name": "My New Dashboard",
  "description": null,
  "configuration": null,
  "enabled": true,
  "created_at": "2013-03-13 22:10:11 -0400",
  "updated_at": "2013-03-13 22:10:11 -0400"
}

Edit Dashboard

The name is the only attribute that should be modified for a dashboard resource.

$ curl -s -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' -d 'name=Network Activity' \
  -X PUT http://127.0.0.1:5000/dashboards/722f417adfa0edcace893b6310625c2b

{
  "json_class": "Dashboard",
  "id": 3,
  "uuid": "722f417adfa0edcace893b6310625c2b",
  "owner": "api@localhost",
  "name": "Network Activity",
  "description": null,
  "configuration": null,
  "enabled": true,
  "created_at": "2013-03-13 22:21:23 -0400",
  "updated_at": "2013-03-13 22:22:50 -0400"
}

Add Graphs to a Dashboard

You may pass one or more comma-delimited graph uuids in the uuids parameter.

$ curl -s -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' -d 'uuids=ac5bf19167c4501a1c584fc03d50a0e3' \
  -X POST http://127.0.0.1:5000/dashboards/722f417adfa0edcace893b6310625c2b/graphs

HTTP/1.1 204 No Content
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
Connection: close
Server: thin 1.2.10 codename Im dumb

Delete a Graph from a Dashboard

$ curl -s -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
-X DELETE  http://127.0.0.1:5000/dashboards/722f417adfa0edcace893b6310625c2b/graphs/ac5bf19167c4501a1c584fc03d50a0e3

HTTP/1.1 204 No Content
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
Connection: close
Server: thin 1.2.10 codename Im dumb

Delete Dashboard

$ curl -i -s -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -X DELETE http://127.0.0.1:5000/dashboards/83aa7d665215dd233abc2850b6025af4

HTTP/1.1 204 No Content
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
Connection: close
Server: thin 1.2.10 codename Im dumb

Metrics

List Metrics

$ curl -s -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' \
  -X GET http://127.0.0.1:5000/metrics/

[
  "carbon.agents.li520-115-a.avgUpdateTime",
  "carbon.agents.li520-115-a.cache.overflow",
  "carbon.agents.li520-115-a.cache.queries",
  "carbon.agents.li520-115-a.cache.queues",
  "carbon.agents.li520-115-a.cache.size",
  "carbon.agents.li520-115-a.committedPoints",
  "carbon.agents.li520-115-a.cpuUsage",
  "carbon.agents.li520-115-a.creates",
  "carbon.agents.li520-115-a.errors",
  "carbon.agents.li520-115-a.memUsage",
  "carbon.agents.li520-115-a.metricsReceived",
  "carbon.agents.li520-115-a.pointsPerUpdate",
  "carbon.agents.li520-115-a.updateOperations"
]

Search Metrics

$ curl -s -H 'Accept: application/json' -H 'X-DESCARTES-API-TOKEN: foobar' -d 'pattern=update' \
  -X GET http://127.0.0.1:5000/metrics/search

[
  "carbon.agents.li520-115-a.avgUpdateTime",
  "carbon.agents.li520-115-a.pointsPerUpdate",
  "carbon.agents.li520-115-a.updateOperations"
]
Clone this wiki locally