Configuration API

Overview

The Geo & ISP restriction allows you to include or exclude certain Countries and/or ISPs from the Streamroot Products activation. With these set of APIs, it is possible to Whitelist or Blacklist Countries and/or ISPs where you want Streamroot Products (Mesh & Orchestrator) to be activated or deactivated depending on your business requirements.

Note
Changes made to a Geo & ISP restriction take up to 10 minutes to be effective.

Authentication

API Key

To use our Data APIs you need to authenticate via API Key. You can get your API Keys from your Streamroot Dashboard in the Profile Section:

Image_2020-09-09_at_4.30.35_PM.png

Customer ID

You will also need your Customer ID which can be found in the Company tab of the Profile section:

Authenticate via API Key

To use our data APIs you need to authenticate via API Key set in the Authorization HTTP header.

Once you have the key, simply add this header to your HTTP requests:

Authorization: API-Key {YOUR_API_KEY}

What is a Geo/ISP Restriction List

A Geo/ISP Restriction List can be created by defining the following fields:

Fields	Type	Description
name	string	The name of the Geo ISP restriction list. Example: "Whitelist France".
type	string	The type of the list. Possible values are "blacklist"and "whitelist"
countries	string	The list of countries where you plan to active/deactivate mesh network. The countries names are case insensitive: you could enter both uppercase and lowercase values and the name of the country must match `country_name` in Maxmind DB
isps	string	The list of Internet Service Provider where you plan to active/deactivate mesh network. ISP names are case insensitive: you could enter both uppercase and lowercase value and We’ll verify that the names you entered are correct by making sure that they match `isp` in Maxmind DB
<YOUR_CUSTOMER_ID>	String	<YOUR_CUSTOMER_ID> is a string parameter which is the unique Customer ID that you are assigned for the Streamroot Product(s) that you use. It can be found in the Company Tab of the Profile Section.
<YOUR_LIST_ID>	String	<YOUR_LIST_ID> is the `geoblockingListId` that is used to identify a Geo/ISP Restriction List. You can use this to point to particular list in an API end point.

Empty Lists

While entering data in a field within a list, it is possible to have some fields where no data has been entered, i.e the field is empty. In that case, an empty list corresponds to missing field.

If a field within a list has no data in it, then it is considered to be a missing field.

Example:

This entry,

{
    "name":"test empty ISP whitelist",
    "type":"whitelist",
    "countries": ["United Kingdom"],
    "isp":[]
}

is equivalent to:

{
    "name":"test empty ISP whitelist",
    "type":"whitelist",
    "countries":["United Kingdom"]
}

Relationships Between Countries and ISPs

When calling an API, it is important to keep in mind the relationships between the Countries and ISPs. The relationship differs depending on whether the list has been Blacklisted or Whitelisted. The fields are related in the following way:

Blacklist

When defining a blacklist, we’ll exclude from the Orchestrator and/or mesh network users who belong to the list of Countries OR the list of ISPs
When a blacklist rule is defined, only the clients whose IP matches the rule are deactivated, all others are activated.

Example

{
    "name":"DNA_Config_1.1",
    "type":"blacklist",
    "countries":["France", "Italy"],
    "isps":["Orange France Mobile", "Wind Tre"]
}

This list will result in all the viewers located in France & Italy (regardless of their ISP) as well as all viewers connected to the Orange France Mobile and Wind Tre (regardless of their country) being deactivated.

Whitelist

When defining a blacklist, we’ll exclude from Orchestrator and/or mesh network users who belong to the list of Countries AND the list of ISPs
When a whitelist rule is defined, only the clients whose IP matches the rule are activated, all the rest are deactivated.

Example

{
    ...
    "type":"whitelist",
    "countries":["United Kingdom", "Spain"],
    "isps":["CenturyLink", "Wind Tre"]
}

This list will result in all the viewers located in United Kingdom & Spain who are connected to either Orange France Mobile or Wind Tre being deactivated.

Step by Step guide to setup a Geo/ISP Restriction List

In order to fully setup and implement a Geo/ISP Restriction List using our APIs, you can follow the following steps:

Create a Geo/ISP Restriction List

You can Create a Geo/ISP Restriction List using the following end-point.
```
POST api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists
```
With this end point, you define which countries and/or ISPs would be blacklisted or whitelisted.
Attach a List to a Property
For a Geo/ISP Restriction list to be active, it needs to be attached to a property (See Property). It can be done using the following end points.

For Mesh
```
 POST  api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/properties 
```
For Orchestrator
```
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/compass/properties
```

Get all properties
If you wish to attach your Geo/ISP Restriction List, you will need to know the name of the Property you wish to attach the list to. To see a list of all the Properties, you can use the following end points:

For Mesh

GET api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/dna/properties

Response Example

 {
        "name": "property_test",
        "activationRatio": 0,
        "superSeederRatio": 0,
        "detectRangeRequest": false,
        "geoblockingListId": "00000000-0000-0000-0000-000000000000",
        "networkActivation": {
            "wifiEthernetUpload": true,
            "wifiEthernetDownload": true,
            "cellularOtherUpload": false,
            "cellularOtherDownload": true
        },
        "ssai": {
            "enabled": false,
            "provider": "",
            "options": null
        },
        "enterprise": {
            "customStunUrls": [],
            "customSignalingUrl": "",
            "localNetworkOnly": false,
            "matching": false,
            "matchingMap": false,
            "matchingMask": false,
            "unknownSubnetAllow": false,
            "mask": 0
        }
    },
    {
        "name": "property_with_geo",
        "activationRatio": 1,
        "superSeederRatio": 1,
        "detectRangeRequest": false,
        "geoblockingListId": "00000000-0000-0000-0000-000000000000",
        "networkActivation": {
            "wifiEthernetUpload": true,
            "wifiEthernetDownload": true,
            "cellularOtherUpload": true,
            "cellularOtherDownload": true
        },
        "ssai": {
            "enabled": false,
            "provider": "",
            "options": ""
        },
        "enterprise": {
            "customStunUrls": [],
            "customSignalingUrl": "",
            "localNetworkOnly": false,
            "matching": false,
            "matchingMap": false,
            "matchingMask": false,
            "unknownSubnetAllow": false,
            "mask": 0
        }
    }

For Orchestrator

GET api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/compass/properties

Response Example

{
        "name": "property_with_geo",
        "activationRatio": 1,
        "cdnListName": "",
        "geoblockingListId": "00000000-0000-0000-0000-000000000000",
        "cdnScoreProvider": {
            "name": "",
            "credentials": {
                "citrixCustomerID": 0,
                "citrixAppID": 0
            }
        }
    },
    {
        "name": "default",
        "activationRatio": 0,
        "cdnListName": "",
        "geoblockingListId": "00000000-0000-0000-0000-000000000000",
        "cdnScoreProvider": {
            "name": "",
            "credentials": {
                "citrixCustomerID": 0,
                "citrixAppID": 0
            }

Update the existing Property with your List
Now that you know which Property you wish to Update, you could do it by copying and pasting the Response Parameter into the Request body of the end point and just modifying the geoblockingListId to

"geoblockingListId" : <YOUR_LIST_ID>

Mesh End Point

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/properties

Orchestrator End Point

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/compass/properties

Request Example

{
        "name": "property_with_geo",
        "activationRatio": 1,
        "superSeederRatio": 1,
        "detectRangeRequest": false,
        "geoblockingListId": <YOUR_LIST_ID>,
        "networkActivation": {
            "wifiEthernetUpload": true,
            "wifiEthernetDownload": true,
            "cellularOtherUpload": true,
            "cellularOtherDownload": true
        },
        "ssai": {
            "enabled": false,
            "provider": "",
            "options": ""
        },

Get the Property the List is attached to.
You can get the Property that has the List attached by using the following end point
```
GET api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/dna/properties/{YOUR_PROPERTY_NAME}
```

Edit the list
You can use the following end point to Edit the List.

PUT api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}

Delete the list
You can use the following end point to Delete the List.

DELETE api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}

List of API endpoints

Given below is a list of all the API endpoints that can be used in order to set up Geo/ISP Restriction Lists:

POST // Create a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists

GET // Get all Geo/ISP Restriction Lists:  api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists

GET // Get one Geo/ISP Restriction List:   api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}

PUT // Update a Geo/ISP Restriction List:  api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}

DEL //  Delete a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}

1. Create a Geo/ISP Restriction List

Allows to define a whitelist or blacklist of countries/ISPs to activate/deactivate the mesh network on.

Endpoint

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists

For Blacklist

Request Body Example for Blacklist

{
    "name":"DNA_Config_1.1",
    "type":"blacklist",
    "countries":["France", "Italy"],
    "isps":["Orange France Mobile", "Wind Tre"]
}

Response Example for Blacklist:

{
 "data": {
 "countries": [
 "France",
 "Italy"
 ],
 "customerId": <YOUR_CUSTOMER_ID>,
 "id": <YOUR_LIST_ID>,
 "isps": [
 "Orange"
 ],
 "name": "DNA_Config_black_test1",
 "type": "blacklist"
 }
}

For Whitelist:

Request Body Example for Whitelist

{
    ...
    "type":"whitelist",
    "countries":["United Kingdom", "Spain"],
    "isps":["CenturyLink", "Wind Tre"]
}

Response Example for Whitelist:

{
 "data": {
 "countries": [
 "United Kingdom",
 "Spain"
 ],
 "customerId": <YOUR_CUSTOMER_ID>,
 "id": <YOUR_LIST_ID>,
 "isps": [
 "CenturyLink",
 "Wind Tre"
 ],
 "name": "DNA_Config_white_test2",
 "type": "whitelist"
 }
}

2. Attach a Geo/ISP Restriction List to a Mesh Property

This allows you to attach a Geo/ISP Restriction Rule created by defining a Whitelist/Blacklist to a Property in Mesh.

For a Restriction list to be active, it needs to be attached to a Property .
This means that you can use different restriction lists for different properties.

Bear in mind that if you are using Orchestrator, you’ll need to attach your restriction list to your Orchestrator properties, and vice versa for Mesh.

Endpoint

POST  api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/properties

Request Body Example

{
    "name": "testGeoIspList",
    "activationRatio": 1,
    "superSeederRatio": 1,
    "detectRangeRequests": true,
    "networkActivation": {
        "wifiEthernetUpload": true,
        "wifiEthernetDownload": true,
        "cellularOtherDownload": true,
        "cellularOtherUpload": true
    },
    "ssai": {
        "enabled": false,
        "provider": "",
        "options": ""
    },
    "geoblockingListId": <YOUR_LIST_ID>
}

Response Example

{
    "name": "property1",
    "activationRatio": 1,
    "superSeederRatio": 1,
    "detectRangeRequest": false,
    "geoblockingListId": "<YOUR_LIST_ID>",
    "networkActivation": {
        "wifiEthernetUpload": true,
        "wifiEthernetDownload": true,
        "cellularOtherUpload": true,
        "cellularOtherDownload": true
    },
    "ssai": {
        "enabled": false,
        "provider": "",
        "options": ""
    },
    "enterprise": {
        "customStunUrls": [],
        "customSignalingUrl": "",
        "localNetworkOnly": false,
        "matching": false,
        "matchingMap": false,
        "matchingMask": false,
        "unknownSubnetAllow": false,
        "mask": 0
    }
}

3. Attach a Geo/ISP Restriction List to an Orchestrator Property

This allows you to attach a Geo/ISP Restriction List created by defining a Whitelist/Blacklist to a Property in Mesh. Doing so allows you to implement the rule by calling the Orchestrator Property in your deliveryClientConfig

Each Property can only have one Geo/ISP Restriction List attached to it so as to avoid conflicts between different Restriction Lists.

End Point

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/compass/properties

Request Example

{
    "name": "testGeoIspList",
    "activationRatio": 1,
    "superSeederRatio": 1,
    "detectRangeRequests": true,
    "networkActivation": {
        "wifiEthernetUpload": true,
        "wifiEthernetDownload": true,
        "cellularOtherDownload": true,
        "cellularOtherUpload": true
    },
    "ssai": {
        "enabled": false,
        "provider": "",
        "options": ""
    },
    "geoblockingListId": <YOUR_LIST_ID>
}

Response Example

 {
    "name": "testGeoIspList",
    "activationRatio": 1,
    "cdnListName": "",
    "geoblockingListId": <YOUR_LIST_ID>,
    "cdnScoreProvider": {
        "name": "",
        "credentials": {
            "citrixCustomerID": 0,
            "citrixAppID": 0
        }
    }
}

4. Get a particular Geo/ISP Restriction List

This can be used to get a particular Geo/ISP Restriction List

End Point

GET api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}

Response Example

{
    "data": {
        "countries": [
            "france"
        ],
        "customerId": <YOUR_CUSTOMER_ID>,
        "id": <YOUR_LIST_ID>,
        "name": "DNA_Config_1.1",
        "type": "blacklist"
    }
}

5. Get all Geo/ISP Restriction Lists

This can be used to get all the active Geo/ISP Restriction Lists

End Point

GET api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists

Response Example

{
    "data": [
        {
            "countries": [
                "france"
            ],
            "customerId": <YOUR_CUSTOMER_ID>,
            "id": <YOUR_LIST_ID>,
            "name": "DNA_Config_1.1",
            "type": "blacklist"
        },
        {
            "countries": [
                "france"
            ],
            "customerId": <YOUR_CUSTOMER_ID>,
            "id": <YOUR_LIST_ID>,
            "name": "DNA_Config_1.2",
            "type": "blacklist"
        }
    ]
}

6. Update a Geo/ISP Restriction List

This can be used to update a particular Geo/ISP Restriction List

End Point

PUT api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}

Request Body Example

{
    "name":"Whitelist (FR) (Orange France Mobile, SFR) - updated",
    "type": "whitelist",
    "countries" : ["France"],
    "isps":["Orange France Mobile", "SFR"]
}

Response Example

7. Delete a Geo/ISP Restriction List

This can be used to delete a particular Geo/ISP Restriction List.

End Point

DELETE api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}

Response Example

It Should return a 204 No Content. This means that the server successfully processed the request, but is not returning any content.

Errors

When an error occurs, the API returns a NON 200 HTTP status code along with a JSON payload containing a message explaining the origin of the failure. Here are some examples:

HTTP 400
{
  "message": "invalid listId"
}

HTTP 500
{
  "error": "empty activation rule is not allowed"
}

Overview

Authentication

API Key

Customer ID

Authenticate via API Key

What is a Geo/ISP Restriction List

Empty Lists

Relationships Between Countries and ISPs

Blacklist

Whitelist

Step by Step guide to setup a Geo/ISP Restriction List

List of API endpoints

1. Create a Geo/ISP Restriction List

For Blacklist

For Whitelist:

2. Attach a Geo/ISP Restriction List to a Mesh Property

3. Attach a Geo/ISP Restriction List to an Orchestrator Property

4. Get a particular Geo/ISP Restriction List

5. Get all Geo/ISP Restriction Lists

6. Update a Geo/ISP Restriction List

7. Delete a Geo/ISP Restriction List

Errors

In this article