Configuration API

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.

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:

Mesh_Data_API_v3_Overview.PNG

 

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. You could enter 1 to N Countries. 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

Example:

"countries" : ["France", "United Kingdom"]
isps string

The list of Internet Service Provider where you plan to active/deactivate mesh network. You could enter 1 to N ISPs. 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 

Example:

"isps" : ["CenturyLink", "Level 3 Communications"]
<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:

  1. 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.

  2. 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
  3. 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
            }
  4. 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": ""
        },
  5. 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}
  6. 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}
  7. 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"
}

In this article