API v1.0 Documentation

API

Variables

When reading this documentation you will find variables in two forms:

  • <variable>: Variables that are between <> have to be replaced by their values in the URL. For example, /api/v1.0/variables/categories/<category> will turn into /api/v1.0/variables/categories/my_category.
  • variable: Variables that are NOT enclosed by <>:
  • If the method is a GET variables that are between <> have to be replaced by their values in the URL. For example, /api/v1.0/variables/categories/<category> will turn into /api/v1.0/variables/categories/my_category.
  • If the method is a POST or a PUT variables variables that are between <> have to be sent as a JSON object.

Responses

All the responses from the agent will be in JSON format and will include three sections:

  • meta: Meta information about the response. For example, request_time, length of the response or if there was any error.
  • parameters: The parameters used for the call.
  • result: The result of the call or a description of the error if there was any.

For example, for the following call:

/api/v1.0/analytics/top_prefixes?limit_prefixes=10&start_time=2015-07-13T14:00&end_time=2015-07-14T14:00&net_masks=20,24

You will get the following response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "meta": {
    "error": false,
    "length": 10,
    "request_time": 11.99163
  },
  "parameters": {
    "end_time": "2015-07-14T14:00",
    "exclude_net_masks": false,
    "limit_prefixes": 10,
    "net_masks": "20,24",
    "start_time": "2015-07-13T14:00"
  },
  "result": [
    {
      "as_dst": 43650,
      "key": "194.14.177.0/24",
      "sum_bytes": 650537594
    },
    ...
    {
      "as_dst": 197301,
      "key": "80.71.128.0/20",
      "sum_bytes": 5106731
    }
  ]
}

Endpoints

Analytics Endpoint

/api/v1.0/analytics/top_prefixes

GET
Description

Retrieves TOP prefixes sorted by the amount of bytes that they consumed during the specified period of time.

Arguments
  • start_time: Mandatory. Datetime in unicode string following the format %Y-%m-%dT%H:%M:%S. Starting time of the range.
  • end_time: Mandatory. Datetime in unicode string following the format %Y-%m-%dT%H:%M:%S. Ending time of the range.
  • limit_prefixes: Optional. Number of top prefixes to retrieve.
  • net_masks: Optional. List of prefix lengths to filter in or out.
  • exclude_net_masks: Optional. If set to any value it will return prefixes with a prefix length not included in net_masks. If set to 0 it will return only prefixes with a prefix length included in net_masks. Default is 0.
  • filter_proto: Optional. If you don’t set it you will get both IPv4 and IPv6 prefixes. If you set it to 4 you will get only IPv4 prefixes. Otherwise, if you set it to 6 you will get IPv6 prefixes.
Returns

A list of prefixes sorted by sum_bytes. The attribute sum_bytes is the amount of bytes consumed during the specified time.

Examples
http://127.0.0.1:5000/api/v1.0/analytics/top_prefixes?limit_prefixes=10&start_time=2015-07-13T14:00&end_time=2015-07-14T14:00
http://127.0.0.1:5000/api/v1.0/analytics/top_prefixes?limit_prefixes=10&start_time=2015-07-13T14:00&end_time=2015-07-14T14:00&net_masks=20,24
http://127.0.0.1:5000/api/v1.0/analytics/top_prefixes?limit_prefixes=10&start_time=2015-07-13T14:00&end_time=2015-07-14T14:00&net_masks=20,24&exclude_net_masks=1

/api/v1.0/analytics/top_asns

GET
Description

Retrieves TOP ASN’s sorted by the amount of bytes that they consumed during the specified period of time.

Arguments
  • start_time: Mandatory. Datetime in unicode string following the format %Y-%m-%dT%H:%M:%S. Starting time of the range.
  • end_time: Mandatory. Datetime in unicode string following the format %Y-%m-%dT%H:%M:%S. Ending time of the range.
Returns

A list of ASN’s sorted by sum_bytes. The attribute sum_bytes is the amount of bytes consumed during the specified time.

Examples
http://127.0.0.1:5000/api/v1.0/analytics/top_asns?start_time=2015-07-13T14:00&end_time=2015-07-14T14:00

/api/v1.0/analytics/find_prefix/<prefix>/<prefix_length>

GET
Description

Finds all prefixes in the system that contains the prefix <prefix>/<prefix_length>

Arguments
  • <<prefix>>: Mandatory. IP prefix of the network you want to find.
  • <<prefix_length>>: Mandatory. Prefix length of the network you want to find.
  • date: Mandatory. Datetime in unicode string following the format '%Y-%m-%dT%H:%M:%S'.
Returns

It will return a dictionary where keys are the IP’s of the BGP peers peering with SIR. Each one will have a list of prefixes that contain the prefix queried.

Examples
$ curl http://127.0.0.1:5000/api/v1.0/analytics/find_prefix/192.2.3.1/32\?date\=2015-07-22T05:00:01
{
  "meta": {
    "error": false,
    "length": 2,
    "request_time": 1.88076
  },
  "parameters": {
    "date": "2015-07-22T05:00:01",
    "prefix": "192.2.3.1/32"
  },
  "result": {
    "193.182.244.0": [
      {
        "as_path": "1299 3356",
        "bgp_nexthop": "62.115.48.29",
        "comms": "1299:20000 8403:100 8403:2001",
        "event_type": "dump",
        "ip_prefix": "192.2.0.0/16",
        "local_pref": 100,
        "origin": 0,
        "peer_ip_src": "193.182.244.0"
      }
    ],
    "193.182.244.64": [
      {
        "as_path": "1299 3356",
        "bgp_nexthop": "80.239.132.249",
        "comms": "1299:20000 8403:100 8403:2001",
        "event_type": "dump",
        "ip_prefix": "192.2.0.0/16",
        "local_pref": 100,
        "origin": 0,
        "peer_ip_src": "193.182.244.64"
      }
    ]
  }
}

/api/v1.0/analytics/find_prefixes_asn/<asn>

GET
Description

Finds all prefixes in the system that traverses and/or originates in <asn>

Arguments
  • <<asn>>: Mandatory. ASN you want to query.
  • date: Mandatory. Datetime in unicode string following the format '%Y-%m-%dT%H:%M:%S'.
  • origin_only: Optional. If set to any value it will return only prefixes that originate in <asn>.
Returns

It will return a dictionary where keys are the IP’s of the BGP peers peering with SIR. Each one will have a list of prefixes that traverses and/or originates in <asn>

Examples
curl http://127.0.0.1:5000/api/v1.0/analytics/find_prefixes_asn/345\?date\=2015-07-22T05:00:01\&origin_only=1
{
  "meta": {
    "error": false,
    "length": 2,
    "request_time": 1.15757
  },
  "parameters": {
    "asn": "345",
    "origin_only": "1",
    "date": "2015-07-22T05:00:01"
  },
  "result": {
    "193.182.244.0": [
      {
        "as_path": "1299 209 721 27064 575 306 345",
        "bgp_nexthop": "62.115.48.29",
        "comms": "1299:25000 8403:100 8403:2001",
        "event_type": "dump",
        "ip_prefix": "55.3.0.0/16",
        "local_pref": 100,
        "origin": 0,
        "peer_ip_src": "193.182.244.0"
      },
      {
        "as_path": "1299 209 721 27065 6025 345",
        "bgp_nexthop": "62.115.48.29",
        "comms": "1299:20000 8403:100 8403:2001",
        "event_type": "dump",
        "ip_prefix": "156.112.250.0/24",
        "local_pref": 100,
        "origin": 0,
        "peer_ip_src": "193.182.244.0"
      }
    ],
    "193.182.244.64": [
      {
        "as_path": "1299 209 721 27064 575 306 345",
        "bgp_nexthop": "80.239.132.249",
        "comms": "1299:25000 8403:100 8403:2001",
        "event_type": "dump",
        "ip_prefix": "55.3.0.0/16",
        "local_pref": 100,
        "origin": 0,
        "peer_ip_src": "193.182.244.64"
      },
      {
        "as_path": "1299 209 721 27065 6025 345",
        "bgp_nexthop": "80.239.132.249",
        "comms": "1299:20000 8403:100 8403:2001",
        "event_type": "dump",
        "ip_prefix": "156.112.250.0/24",
        "local_pref": 100,
        "origin": 0,
        "peer_ip_src": "193.182.244.64"
      }
    ]
  }
}

Variables Endpoint

/api/v1.0/variables

GET
Description

Retrieves all the variables in the system.

Arguments
Returns

A list of all the variables.

Examples
http://127.0.0.1:5000/api/v1.0/variables
POST
Description

You can create a variable from the CLI with curl like this:

curl -i -H "Content-Type: application/json" -X POST -d '{"name": "test_var", "content": "whatever", "category": "development", "extra_vars": {"ads": "qwe", "asd": "zxc"}}' http://127.0.0.1:5000/api/v1.0/variables
Arguments
  • content: Content of the variable.
  • category: Category of the variable.
  • name: Name of the variable.
  • extra_vars: Use this field to add extra data to your variable. It is recommended to use a JSON string.
Returns

The variable that was just created.

Examples

/api/v1.0/variables/categories

GET
Description

Retrieves all the categories in the system.

Arguments
Returns

A list of all the categories.

Examples
http://127.0.0.1:5000/api/v1.0/variables/categories

/api/v1.0/variables/categories/<category>

GET
Description

Retrieves all the variables the belong to <category> in the system.

Arguments
  • <category>: Category you want to query.
Returns

A list of variables belonging to <category>.

Examples
http://127.0.0.1:5000/api/v1.0/variables/categories/<category>

/api/v1.0/variables/categories/<category>/<name>

GET
Description

Retrieves the variable with <name> and <category>.

Arguments
  • <category>: Category of the variable you want to retrieve.
  • <name>: Name of the variable you want to retrieve.
Returns

A list of variables belonging to <category>.

Examples
http://127.0.0.1:5000/api/v1.0/variables/categories/<category>/<name>
PUT
Description

This API call allows you to modify all of some of the values of a variable. For example, you can update the name and the extra_vars of a variable with the following command:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
 curl -i -H "Content-Type: application/json" -X PUT -d '{"name": "test_varc", "extra_vars": "{'my_param1': 'my_value1', 'my_param2': 'my_value2'}"}' http://127.0.0.1:5000/api/v1.0/variables/categories/development/test_vara HTTP/1.0 200 OK Content-Type: application/json Content-Length: 358 Server: Werkzeug/0.10.4 Python/2.7.8 Date: Tue, 21 Jul 2015 10:16:22 GMT
 {
  "meta": {
    "error": false,
    "length": 1,
    "request_time": 0.0055
  },
  "parameters": {
    "categories": "development",
    "name": "test_vara"
  },
  "result": [
    {
      "category": "development",
      "content": "whatever",
      "extra_vars": "{my_param1: my_value1, my_param2: my_value2}",
      "name": "test_varc"
    }
  ]
  }
Arguments
  • category: Optional. New category.
  • content: Optional. New content.
  • name: Optional. New name.
  • <name>: Name of the variable you want to modify.
  • <category>: Category of the variable you want to modify.
  • extra_vars: Optional. New extra_vars.
Returns

The variable with the new data.

Examples
http://127.0.0.1:5000/api/v1.0/variables/categories/<category>/<name>
DELETE
Description

Deletes a variable. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 curl -i -X DELETE http://127.0.0.1:5000/api/v1.0/variables/categories/deveopment/test_vara HTTP/1.0 200 OK Content-Type: application/json Content-Length: 183 Server: Werkzeug/0.10.4 Python/2.7.8 Date: Tue, 21 Jul 2015 10:17:27 GMT
 {
  "meta": {
    "error": false,
    "length": 0,
    "request_time": 0.0016
  },
  "parameters": {
    "categories": "deveopment",
    "name": "test_vara"
  },
  "result": []
 }
Arguments
  • <category>: Category of the variable you want to delete.
  • <name>: Name of the variable you want to delete.
Returns

An empty list.

Examples
http://127.0.0.1:5000/api/v1.0/variables/categories/<category>/<name>

Pmacct Endpoint

/api/v1.0/pmacct/dates

GET
Description

Retrieves all the available dates in the system.

Arguments
Returns

A list of all the available dates in the system.

Examples
http://127.0.0.1:5000/api/v1.0/pmacct/dates

/api/v1.0/pmacct/flows

GET
Description

Retrieves all the available dates in the system.

Arguments
  • start_time: Mandatory. Datetime in unicode string following the format '%Y-%m-%dT%H:%M:%S'. Starting time of the range.
  • end_time: Mandatory. Datetime in unicode string following the format '%Y-%m-%dT%H:%M:%S'. Ending time of the range.
Returns

A list of all the available dates in the system.

Examples
http://127.0.0.1:5000/api/v1.0/pmacct/flows?limit_prefixes=10&start_time=2015-07-14T14:00&end_time=2015-07-14T14:01
http://127.0.0.1:5000/api/v1.0/pmacct/flows?limit_prefixes=10&start_time=2015-07-13T14:00&end_time=2015-07-14T14:00

/api/v1.0/pmacct/bgp_prefixes

GET
Description

Retrieves all the BGP prefixes in the system.

Arguments
  • date: Mandatory. Datetime in unicode string following the format '%Y-%m-%dT%H:%M:%S'.
Returns

A list of all the available BGP prefixes in the system.

Examples
http://127.0.0.1:5000/api/v1.0/pmacct/bgp_prefixes?date=2015-07-16T11:00:01

/api/v1.0/pmacct/raw_bgp

GET
Description

Retrieves the BGP raw data from pmacct. That includes AS PATH, local-pref, communities, etc....

Warning

Do it only if need it. If you have the full feed this can return hundreds of MB of data.

Arguments
  • date: Mandatory. Datetime in unicode string following the format '%Y-%m-%dT%H:%M:%S'.
Returns

The raw data from pmacct.

Examples
http://127.0.0.1:5000/api/v1.0/pmacct/raw_bgp?date=2015-07-16T11:00:01

/api/v1.0/pmacct/purge_bgp

GET
Description

Deletes all the BGP data that is older than older_than.

Arguments
  • older_than: Mandatory. Datetime in unicode string following the format '%Y-%m-%dT%H:%M:%S'.
Returns

The list of files containing BGP data that was deleted.

Examples
http://127.0.0.1:5000/api/v1.0/pmacct/purge_bgp?older_than=2015-07-29T13:00:01

/api/v1.0/pmacct/purge_flows

GET
Description

Deletes all the flows that are older than older_than.

Arguments
  • older_than: Mandatory. Datetime in unicode string following the format '%Y-%m-%dT%H:%M:%S'.
Returns

The flows that were deleted.

Examples
http://127.0.0.1:5000/api/v1.0/pmacct/purge_flows?older_than=2015-07-29T13:00:01