Facette
Table of Contents

Library API

All library items are identified by an universally unique identifier (UUID), each 36 characters long.

Groups

List groups

GET /api/v1/library/sourcegroups/
GET /api/v1/library/metricgroups/

Returns an array of objects listing the available groups.

Optional parameters:

Response:

[
    {
        "id": "386c8361-517f-404e-6c34-870983ab66e8",
        "name": "group0",
        "description": "A great group description.",
        "modified": "2013-01-02T12:34:56+01:00"
    }
]

A X-Total-Records HTTP header containing the total number of records is returned along with the response.

Get a single group

GET /api/v1/library/sourcegroups/<id>
GET /api/v1/library/metricgroups/<id>

Returns a group object with its name, description and matching rules entries.

Response:

{
    "id": "386c8361-517f-404e-6c34-870983ab66e8",
    "name": "group0",
    "description": "A great group description.",
    "entries": [
        {
            "origin": "origin0",
            "pattern": "glob:example.*"
        }
    ]
}

Create a new group

POST /api/v1/library/sourcegroups/
POST /api/v1/library/metricgroups/

Takes a group from the request body and stores it in the library, then returns a Location HTTP header pointing to the newly created item location.

Optional parameters:

Additional status codes:

See Get a single group above for group object format.

Update an existing group

PUT /api/v1/library/sourcegroups/<id>
PUT /api/v1/library/metricgroups/<id>

Takes a group from the request body and overwrites an existing library group item.

Additional status codes:

See Get a single group above for group object format.

Delete an existing group

DELETE /api/v1/library/sourcegroups/<id>
DELETE /api/v1/library/metricgroups/<id>

Removes an existing group item from the library.

Additional status codes:

Expand query tuples

POST /api/v1/library/expand

Takes an array of query tuples from the request body and returns their expanded versions.

A query tuple consists of a list of 3 values: origin, source and metric.

When querying the back-end, both source and metric fields can be a reference to a group, then beginning with group: prefix.

[
        ["origin0", "host1.renm.org", "group:group0"]
]

Response:

[
    [
        ["origin0", "host1.renm.org", "metric0"],
        ["origin0", "host1.renm.org", "metric1"],
        ["origin0", "host1.renm.org", "metric2"],
        ["origin0", "host1.renm.org", "metric3"]
    ]
]

Scales

List scales

GET /api/v1/library/scales/

Returns an array of objects listing the available scales.

Optional parameters:

Response:

[
    {
        "id": "95e7f164-9ad1-4e7a-7e44-02783f1f3c2c"
        "name": "scale0",
        "description": "A great scale description.",
        "modified": "2013-01-02T12:34:56+01:00"
    }
]

A X-Total-Records HTTP header containing the total number of records is returned along with the response.

Get a single scale

GET /api/v1/library/scales/<id>

Returns a scale object with its name, description and matching rules entries.

Response:

{
    "id": "95e7f164-9ad1-4e7a-7e44-02783f1f3c2c"
    "name": "scale0",
    "description": "A great scale description.",
    "value": 1.345
}

Create a new scale

POST /api/v1/library/scales/

Takes a scale from the request body and stores it in the library, then returns a Location HTTP header pointing to the newly created item location.

Optional parameters:

Additional status codes:

See Get a single scale above for scale object format.

Update an existing scale

PUT /api/v1/library/scales/<id>

Takes a scale from the request body and overwrites an existing library scale item.

Additional status codes:

See Get a single scale above for scale object format.

Delete an existing scale

DELETE /api/v1/library/scales/<id>

Removes an existing scale item from the library.

Additional status codes:

Get scales values

GET /api/v1/library/scales/values

Returns an array of objects listing the available scales along with their names and values.

Response:

[
    {
        "name": "scale0",
        "value": 1.234
    }
]

Units new in version 0.2

List units

GET /api/v1/library/units/

Returns an array of objects listing the available units.

Optional parameters:

Response:

[
    {
        "id": "8d07dedd-cfaf-4041-a625-12a390e76f86"
        "name": "unit0",
        "description": "A great unit description.",
        "modified": "2013-01-02T12:34:56+01:00"
    }
]

A X-Total-Records HTTP header containing the total number of records is returned along with the response.

Get a single unit

GET /api/v1/library/units/<id>

Returns a unit object with its name, description and matching rules entries.

Response:

{
    "id": "8d07dedd-cfaf-4041-a625-12a390e76f86"
    "name": "unit0",
    "description": "A great unit description.",
    "value": 1.345
}

Create a new unit

POST /api/v1/library/units/

Takes a unit from the request body and stores it in the library, then returns a Location HTTP header pointing to the newly created item location.

Optional parameters:

Additional status codes:

See Get a single unit above for unit object format.

Update an existing unit

PUT /api/v1/library/units/<id>

Takes a unit from the request body and overwrites an existing library unit item.

Additional status codes:

See Get a single unit above for unit object format.

Delete an existing unit

DELETE /api/v1/library/units/<id>

Removes an existing unit item from the library.

Additional status codes:

Get units labels

GET /api/v1/library/units/labels

Returns an array of objects listing the available units along with their names and labels.

Response:

[
    {
        "name": "unit0",
        "label": "A"
    }
]

Graphs

List graphs

GET /api/v1/library/graphs/

Returns an array of objects listing the available graphs.

Optional parameters:

Response:

[
    {
        "id": "909fe2df-3064-4ee2-5f52-4eca2c953c76",
        "name": "graph0",
        "description": "A great graph description.",
        "modified": "2013-01-02T12:34:56+01:00"
    }
]

A X-Total-Records HTTP header containing the total number of records is returned along with the response.

Get a single graph

GET /api/v1/library/graphs/<id>

Returns a graph object with its name, description, type and groups definitions.

Response:

{
    "id": "909fe2df-3064-4ee2-5f52-4eca2c953c76",
    "name": "graph0",
    "description": "A great graph description.",
    "type": 1,
    "groups": [
        {
            "name": "serie0",
            "type": 0,
            "stack_id": 0,
            "series": [
                {
                    "name": "serie0",
                    "origin": "origin0",
                    "source": "source0",
                    "metric": "metric0",
                    "options": {
                        "scale": 1.234
                    }
                }
            ],
            "options": {}
        }
    ],
    "stack_mode": 0,
    "unit_legend": "A great legend",
    "unit_type": 2
}

or for a graph template instance:

{
    "id": "34a15691-5872-462f-7c42-177c18dd8a00",
    "name": "server1.example.net - load",
    "description": "Load average for server1.example.net",
    "template": false,
    "link": "dcde7cf8-f637-4303-592e-402ba3e9f017",
    "attributes": {
        "source": "server1.example.net"
    }
}

Graph types:

Stack modes:

Unit types:

Group and serie options:

Create a new graph

POST /api/v1/library/graphs/

Takes a graph from the request body and stores it in the library, then returns a Location HTTP header pointing to the newly created item location.

Optional parameters:

Additional status codes:

See Get a single graph above for graph object formats.

Templates new in version 0.3

To create a graph template, template property must be set to true. The following properties are suitable to template expansion:

Template attributes must follow Go template syntax (e.g. {{ .attr1 }}).

To instantiate a template, both link and attributes properties must be provided. Being respectively, the identifier of the template being instantiated and an object specifying attributes values (see Get a single graph example above).

Update an existing graph

PUT /api/v1/library/graphs/<id>

Takes a graph from the request body and overwrites an existing library graph item.

Additional status codes:

See Get a single graph above for graph object format.

Delete an existing graph

DELETE /api/v1/library/graphs/<id>

Removes an existing graph item from the library.

Additional status codes:

Collections

List collections

GET /api/v1/library/collections/

Returns an array of objects listing the available collections.

Optional parameters:

Response:

[
    {
        "id": "916f955a-752c-468f-61b3-ace173a6d2da",
        "name": "collection0",
        "description": "A great collection description.",
        "parent": null,
        "has_children": false,
        "modified": "2013-01-02T12:34:56+01:00"
    }
]

A X-Total-Records HTTP header containing the total number of records is returned along with the response.

Get a single collection

GET /api/v1/library/collections/<id>

Returns a collection object with its name, description and graphs entries.

Response:

{
    "id": "916f955a-752c-468f-61b3-ace173a6d2da",
    "name": "collection0",
    "description": "A great collection description.",
    "entries": [
        {
            "id": "909fe2df-3064-4ee2-5f52-4eca2c953c76",
            "options": {
                "title": "Chart title",
                "sample": "400",
                "range": "-30d",
                "percentiles": "95",
                "constants": ""
            }
        }
    ]
}

Create a new collection

POST /api/v1/library/collections/

Takes a collection from the request body and stores it in the library, then returns a Location HTTP header pointing to the newly created item location.

Optional parameters:

Additional status codes:

See Get a single collection above for group object format.

Update an existing collection

PUT /api/v1/library/collections/<id>

Takes a collection from the request body and overwrites an existing library collection item.

Additional status codes:

See Get a single collection above for group object format.

Delete an existing collection

DELETE /api/v1/library/collections/<id>

Removes an existing collection item from the library.

Additional status codes:

Examples

To create a source group using the API:

$ curl -i -X POST -H 'Content-Type: application/json' -d '{
    "name": "group0",
    "description": "A great group description.",
    "entries": [
        {
            "origin": "origin0",
            "pattern": "glob:example.*"
        }
    ]
}' http://127.0.0.1:12003/api/v1/library/sourcegroups/
HTTP/1.1 201 Created
Cache-Control: private, max-age=0
Date: Thu, 15 Jan 2015 18:01:05 GMT
Expires: Thu, 15 Jan 2015 18:01:05 GMT
Location: /api/v1/library/sourcegroups/9c1133ee-b685-4735-4cf9-529c7eb4bd23
Content-Length: 0
Content-Type: text/plain; charset=utf-8

Note: don’t specify a id parameter when creating a resource, the back-end assigns an unique identifier at creation.

The URI of the resource created is provided by the Location header. To retrieve the group just created:

$ curl http://127.0.0.1:12003/api/v1/library/sourcegroups/9c1133ee-b685-4735-4cf9-529c7eb4bd23
{"id":"9c1133ee-b685-4735-4cf9-529c7eb4bd23","name":"group0","description":"A great group description.","entries":[{"pattern":"glob:example.*","origin":"origin0"}]}