The current InterCloud API provides routes to retrieve your groups’ used capacity per region.
If you are an InterCloud services reseller, you may want to retrieve all capacities, across all your children’s groups.
This document is a step-by-step guide to doing that using our current API.
The procedure can be summed up as:
- Retrieve current user organization ID
- Retrieve child organization IDs
- For every child organization,
- List all Groups belonging to an organization
- Collect regional capacity for each group
Authentication : Generate a Bearer access token
Authentication to the API is done via a Bearer access token. Your application can generate a 1-hour access token as explained below. You can also use a Personal Access Token, more suitable for one-off users (scripts, etc.)
The generated token shall then be included in all of your request headers.
Generate a Personal Access Token
You can generate and manage Personal Access Tokens via the Account Settings section of InterCloud Portal. These tokens have configurable expiration time. This type of token is best for on-off usages (scripts, etc.)
Generate an API access token (one hour validity)
If you’re developing a full application, you might prefer to use programatically generated tokens. These tokens expire after one hours’ time.
To create an access token the user needs to have an account into the InterCloud Console. The following endpoint needs to be used:
POST /auth/token
Headers:
-H "Content-Type:application/json"
-H 'authorization:Basic <basic_token>'
<basic_token> will be provided on-demand by InterCloud
Body:
{
"grant_type": "password",
"password": "titi tata toto",
"scope": "everything",
"username": "admin@parent.com"
}
username: user account username
password: user account password
Response:
{
"access_token": "wYMd38feTwSDoekqi251Eg",
"expires_in": 3600,
"refresh_token": "aEji5l66QhW7rsb8_IM0vQ",
"scope": "everything",
"token_type": "Bearer"
}
access_token: access token
expires_in: expiration period in seconds
Retrieving organization information
Retrieve all your organization IDs
The current user organization id can be retrieved using the following call:
GET /me/info
Headers:
-H 'authorization:Bearer <personal_access_token>'
The response gives detailed information of the current user:
{
"id": "70876bdc-eb28-427d-94d7-30fb384ae7d6",
"createdAt": "2020-06-26T10:23:26.672563Z",
"updatedAt": "2020-06-26T10:23:50.369896Z",
"lastname": "test",
"firstname": "test",
"email": "admin@parent.com",
"role": "admin",
"contact": null,
"preference": null,
"login": {
"id": "f67574d0-57c1-4220-9174-f0cc09f3bd11",
"createdAt": "2020-06-26T10:26:05.655184Z",
"updatedAt": "2020-06-26T11:59:36.679991Z",
"userId": "70876bdc-eb28-427d-94d7-30fb384ae7d6",
"firstLoginAt": "2020-06-26T10:26:05.562083Z",
"numberLogin": 3,
"numberFaileLogin": 0,
"lastLoginAt": "2020-06-26T11:59:36.554576Z",
"lastFailedLoginAt": "0001-01-01T00:00:00Z",
"userAgentFirstLogin": "Go-http-client/1.1",
"ipFirstLogin": ""
},
"organisationId": "a9910752-3a6b-44db-88b0-ac558614ac99"
}
Use the current user’s organisation ID to retrieve all of your children’s IDs in the following request:
GET /organisations/<organisationID>
Headers:
-H 'authorization:Bearer <personal_access_token>'
The response gives a list of all children organizations and the current organization details:
{
"id": "a9910752-3a6b-44db-88b0-ac558614ac99",
"name": "Parent orga",
"address": {
"id": "009d5c97-7105-4fe9-a856-b3504491f757",
"createdAt": "2020-06-26T09:52:20.215053Z",
"updatedAt": "2020-06-26T09:52:20.215053Z",
"organisationId": "a9910752-3a6b-44db-88b0-ac558614ac99",
"street": "d",
"city": "d",
"zipcode": "d",
"country": "d"
},
"capacities": null,
"invoice": {
"id": "7b900b35-b681-467e-87ca-c953f0860ef2",
"createdAt": "2020-06-26T09:52:20.216173Z",
"updatedAt": "2020-06-26T09:52:20.216173Z",
"organisationId": "a9910752-3a6b-44db-88b0-ac558614ac99",
"tvasubjection": false,
"tvanumber": "",
"tvaintra": ""
},
"phone": "d",
"parentId": "11007c0f-1cea-418c-a7bd-7b2e43bc4892",
"children": [
{
"id": "2b8214f2-0142-43ed-872d-b39cdf4c1255",
"name": "Sub-orga 1",
"reseller": false,
"childrenCount": 0
},
{
"id": "643c72b8-275d-4e60-8931-bdaca3877e56",
"name": "Sub-orga 2",
"reseller": false,
"childrenCount": 0
}
],
"reseller": true
}
Accessing a child organization’s resources
If your organization is a reseller of InterCloud services, you’ll be able to access your child organization’s resources by adding the InterCloud-Scope header to your requests.
If this header is omitted, you’ll be viewing your own resources. Examples are given in the next section.
List all Groups belonging to an organization
The Groups list can be retrieved by using the simple endpoint:
GET /groups
Headers:
-H 'authorization:Bearer <personal_access_token>'
Used without any particular header, this call returns the current organization group list.
In order to list the Groups of a child organization, the Intercloud-Scope header must be added to the request
-H "intercloud-scope:<parent_organization_ID>"
<parent_organization_ID> must be replaced by the organizationID retreived by me/info
Response looks like:
{
"id": "65d641e3-adcc-489f-b1e9-f4997d25ad75",
"createdAt": "2020-06-26T10:02:22.996745Z",
"updatedAt": "2020-06-26T10:02:22.996745Z",
"irn": "irn:group:b39cdf4c1255::16d2xtw",
"name": "Europe 2",
"description": "",
"organisationId": "2b8214f2-0142-43ed-872d-b39cdf4c1255",
"allocatedCapacity": null,
"tagIds": null,
"countConnectors": 1,
"countFlowConnectors": 0,
"countLinks": 0,
"countFlowLinks": 0
}
The irn of this group will be used to collect metrics such as used capacity.
Introduction to InterCloud Portal Metrics
What is a Metric ?
The metrics API endpoint provides a way to query metrics or KPIs from different monitoring back-ends, without having to deal with their request formats.
The metrics API endpoint is organized by resource.
The process is:
- Retrieve the resource’s unique InterCloud ID (IRN, see next section)
- Get the list of available metrics for this resource
- Run (ie. query) the metric to retrieve data
What is an IRN ?
IRN stands for InterCloud Resource Name.
An IRN is a string that uniquely identifies an InterCloud resource. It gathers the resource family information, the resource owner and a unique identifier.
Please find below an example of IRN:
irn:geoentrypoint:1hv0g4w1k2rkg::t2cxj9
What are the available Metric Types ?
The InterCloud portal provides 2 types of measurements:
timeseries: This type of metric provides a list of measures with timestamps (example: input or output bandwidth of a connector, measurement of the jitter)status: This type of metric provides a specific status of a resource (example: BGP session is up or down)
There are several different measurement metrics for each type of metrics.
How to run a Metric ?
In InterCloud’s terminology, running a metric means performing a query with the desired parameters (for, eg. start/end dates, etc).
The request format to run a specific metric is:
GET /metrics/query/irn/<irn>/<metric_type>/run?start-d=<s_timestamp>&end-d=<e_timestamp>
The parameters are:
<irn>: this is the IRN value of the monitored resource<metric_type>: the metric to collect<s_timestamp>: this is a timestamp to start the monitoring scale<e_timestamp>: this is a timestamp to end the monitoring scale
Example:
GET /metrics/query/irn/irn:links:1jeqjrcewkrkg::3u217p/latency/run?start-d=2019-03-17T12:03:01%2B01:00&end-d=2019-03-18T12:03:01%2B01:00
List available group metrics : Regional Used Capacity
The following request list all available metrics for a group:
GET /metrics/query/irn/<group_irn>
<group_irn> must be replaced by the targeted group’s IRN, retrieved with GET /groups
If the targeted organization isn’t the one of the current user, the InterCloud-Scope header is mandatory.
-H 'authorization:Bearer <personal_access_token>'
-H "InterCloud-Scope: <parent_organization_ID>"
The response is:
[
{
"name": "latin-america",
"type": "timeserie"
},
{
"name": "japan",
"type": "timeserie"
},
{
"name": "south-africa",
"type": "timeserie"
},
{
"name": "southeast-asia",
"type": "timeserie"
},
{
"name": "north-america",
"type": "timeserie"
},
{
"name": "europe",
"type": "timeserie"
},
{
"name": "pacific",
"type": "timeserie"
}
]
All the metrics listed in the response above provide the used capacity in a given region. There are currently 7 regions in InterCloud’s service offer.
Query group metrics
The /run query described above can be used as follows to retrieve a group’s used capacity.
GET /metrics/query/irn/<irn>/<metric_type>/run?start-d=<s_timestamp>&end-d=<e_timestamp>
Possible values for metric_type are: europe, japan, latin-america, north-america, pacific, south-africa,southeast-asia.
Headers:
-H 'authorization:Bearer <personal_access_token>'
-H "intercloud-scope:<parent_organization_ID>"
Here’s what the response looks like:
{
"type": "timeserie",
"measure": "Used Capacity",
"axis": {
"non_negative_derivative": {
"unit": "bps",
"title": ""
}
},
"Results": [
{
"Series": [
{
"name": "interface_snmp",
"columns": [
"time",
"sum"
],
"values": [
[
"2020-06-24T12:30:00Z",
355.37333333333333
],
[
"2020-06-24T12:35:00Z",
389.58666666666664
],
[
"2020-06-24T12:40:00Z",
3637.6222222391766
],
[
"2020-06-24T12:45:00Z",
26894.48444442749
],
[
"2020-06-24T12:50:00Z",
14125.12444442749
],
[
"2020-06-24T12:55:00Z",
2812.2222222391765
]
]
}
],
"Messages": null
}
]
}
Data points are stored in bps every 5 minutes. The preferred time interval for the request is one day, above this value data is aggregated.
If the metric request is done on the exact same time period over all Groups, received timestamps will be aligned and easier to aggregate.
- InterCloud July 2020 *