Openmix API

Openmix JavaScript Application API

Application

The Openmix application has the following format:

var request_handler;
 
request_handler = (function() {
    'use strict';
    return function(request, response) {
        // Response processing, such as response.respond and response.setTTL
        return;
    };
}());
 
function init(config) {
    'use strict';
    // Application config, such as config.requireProvider
    return;
}
 
function onRequest(request, response) {
    'use strict';
    request_handler(request, response);
}

Functions

init(config)

The init function is called once per application instance. It's main purpose is to declare what providers the app intends to use. All providers used for Openmix decision responses or as Fusion inputs should be declared in this function.

config - (Configuration) - Used to define the available providers and application configuration.

function init(config) {
    // provider_1, provider_2 and provider_3 are provider aliases
    config.requireProvider('provider_1');
    config.requireProvider('provider_2');
    config.requireProvider('provider_3');
}

onRequest(request, response)

This onRequest function is called for each DNS request to generates the response.

request - (Request) - Contains information about the current request.
response - (Response) - Used for specifying the DNS decision response and diagnostic data.

function onRequest(request, response) {
    // Specify the provider alias and CNAME (or IP address)
    response.respond('edgecast', 'www.example.edgecastcdn.net');
 
    response.setTTL(600);
}

onFusion(provider, fusion_data)

This function is called when new fusion data is available, and can be used to maintain fusion data in memory, amortizing parse costs across requests. Defining this function is optional.

provider - (String) - The provider whose fusion data changed.
fusion_data - (String) - The fusion data.

In the following example, the global variable fusion_cache has the same content as the request variable fusion_local. A helper function called parseFusionData is used.

var fusion_cache = {};
function onFusion(provider, fusion_data) {
    fusion_cache[provider] = fusion_data;
}

function onRequest(request, response) {
    var fusion_local = parseFusionData(request.getData('fusion'));
    // fusion_local == fusion_global
    ...
}

// Fusion data is provided as an object mapping Fusion provider
// alias to a string. In this example, the strings are expected
// to be JSON-formatted.
function parseFusionData(data) {
    var keys = Object.keys(data),
        i = keys.length,
        key;
    while (i--) {
        key = keys[i];
        try {
            data[key] = JSON.parse(data[key]);
        }
        catch (e) {
            delete data[key];
        }
    }
    return data;
}

Configuration

The Configuration object is used to define the input requirements of the application and the response profiles. This information is used by the worker during initialization. The worker will place an application in fallback mode if it cannot provide the input required by the application.

Functions

requireProvider(alias)

alias - (string) - Provider alias name.

Makes the probe data for the specified provider available to the Openmix application and configures the provider decisions available for reporting. The alias name that is used is specified as part of the provider definition.

Providers can be used without being declared in an Openmix application. However the decisions for the provider will not be aggregated in the reporting.

config.requireProvider('provider_alias');

enableCors(hosts) - (HTTP)

hosts - (string) - Hosts that should be allowed to access the application via CORS.

The hosts are specified in a comma separated list, including protocol, or wildcard ('*') for all source hosts to be able to access the application endpoint. It should be in the init(config) function.

config.enableCors('http://www.mydomain.com');

or

config.enableCors('*');

enableProximityData(flag) - (DNS)

flag - (bool) - Flag for enabling Static-Proximity feature (default arg is set to true).

Makes the Static-Proximity probe data for the specified application instance available.

The Static-Proximity data are actual pre-calculated distances, with latitude and longitude, between platforms and user's location.

Be cautious while using them, because not all platforms include GEO information. All platforms in "Cloud Computing" and "Cloud Storage" categories do include GEO information.

config.enableProximityData(true);

or

config.enableProximityData();

Request

The Request object provides information about the current DNS request.

Properties

Name	Type	Description	Method Type
asn	Integer	The Autonomous System Number for the network from which the request originated. If the request uses edns-client-subnet (ECS), this value will be based on the client IP subnet otherwise it will be based on DNS resolver for the request.	DNS/HTTP
market	String	A two-letter code identifying the geographic continent from where the request originated. If the request uses edns-client-subnet (ECS), this value will be based on the client IP subnet otherwise it will be based on DNS resolver for the request.	DNS/HTTP
country	String	The ISO code representing the country of the DNS resolver from which the request originated. If the request uses edns-client-subnet (ECS), this value will be based on the client IP subnet otherwise it will be based on DNS resolver for the request.	DNS/HTTP
region	String	A string representing the sub-country region from which the request originated. If the request uses edns-client-subnet (ECS), this value will be based on the client IP subnet otherwise it will be based on DNS resolver for the request.	DNS/HTTP
state	String	A string representing the state or province from which the request originated. If the request uses edns-client-subnet (ECS), this value will be based on the client IP subnet otherwise it will be based on DNS resolver for the request.	DNS/HTTP
ip_address	String	The IP address of the DNS resolver from which the request originated. If the request uses edns-client-subnet (ECS), this value will be the client IP subnet otherwise it will be the IP of the DNS resolver for the request.	DNS/HTTP
resolver_asn	Integer	The Autonomous System Number for the network of the DNS resolver from which the request originated.	DNS
resolver_market	String	A two-letter code identifying the geographic continent of the DNS resolver from which the request originated.	DNS
resolver_country	String	The ISO code representing the country of the DNS resolver from which the request originated.	DNS
resolver_region	String	A string representing the sub-country region of the DNS resolver from which the request originated.	DNS
resolver_state	String	A string representing the state or province of the DNS resolver from which the request originated.	DNS
resolver_ip_address	String	The IP address of the DNS resolver from which the request originated.	DNS
hostname_prefix	String	Any dotted portion of the domain name preceding the application id. For example, if the DNS request is made for prefix.2-01-29a4-002d.cdx.cedexis.net, then request.hostname_prefix will be set to "prefix"	DNS
query_type	String	Returns a string that indicates the type of record request being processed in the application. See below for possible values.	DNS

Country

Country strings are formatted as ISO 3166-1 alpha-2 country codes. Some example values:

Code	Country Name
BR	Brazil
CN	China
FR	France
MX	Mexico
US	United States
...	...

See ISO codes on Wikipedia for the full list.

Region

Region strings are a combination of the parent country ISO code and the name of the region. All regions are contained within a single country. Region names that contain spaces are concatenations of the first letter of each word.

The region strings are of the format: "XX-R-YYY"

where XX is the country ISO code, YYY is the region name or abbreviation.

The code for a region can be retrieved through the regions API. You can find more information on using the API and access regions API in the Cedexis Portal.

State

State strings are a combination of the parent country ISO code and the name of the state. All state are contained within a single country. State names that contain spaces are concatenations of the first letter of each word.

The state strings are of the format: "XX-S-YYY"

where XX is the country ISO code, YYY is the state name or abbreviation.

The code for a state can be retrieved through the states API. You can find more information on using the API and access states API in the Cedexis Portal.

Market

Market codes are two upper case characters. The following market values are available:

Code	Market
NA	North America
OC	Oceania
EU	Europe
AS	Asia
AF	Africa
SA	South America

Query Type - (DNS)

Returns a string that indicates the type of record request being processed in the application.

Value	Description
A	IPv4 address record
AAAA	IPv6 address record
CNAME	Canonical name record

function onRequest(request, response) {
    ...
    var type = request.query_type();

    // type = "A"
}

Functions

getProbe(probe_name)

probe_name - (string) - Name of probe values to retrieve from providers.

Returns an object that includes the specified probe values of each provider. A provider that does not have the specified probe is not present in the object.

function onRequest(request, response) {
    ...
    var avail = request.getProbe('avail');

    // avail = {
    //    'provider_1': { 'avail': 98.9 }, 
    //    'provider_3': { 'avail': 96.1 }
    // }  
}

Please refer to the section "Retrieving Data" for more details on the data that can retrieved from the Radar probes.

getData(feed_name)

feed_name - (string) - Name of feed to retrieve.

Returns an object that includes the data for the specified feed.

Value	Description
fusion	Data from a Fusion feed configured for the application

Note: All of the values in the returned object are strings and should be converted to a number if math operators are used.

function onRequest(request, response) {
    ...
    var fusion = request.getData('fusion');

    // fusion = {
    //     'provider_1': 
    //         'health_score': {
    //             'unit': "0-5",
    //             'value': 5
    //         }, 
    //     ...
    //     }  
}

getHeader(header_name) - (HTTP)

header_name - (string) - Name of HTTP header value to retrieve

Returns a string containing the specified header value from the HTTP request. If the header value does not exist null is returned.

var sample_header = request.getHeader('X-Sample-Header');

getQueryString(query_name) - (HTTP)

query_name - (string) - Name of HTTP query string value to retrieve.

Returns a string containing the specified query string value from the HTTP URL. If the query name does not exist, null is returned.

var sample_string = request.getQueryString('sample');

Response

The Response object is used to specify the DNS decision.

Functions

addCName(cname) - (DNS)

Adds the specified CNAME to the DNS response.

function onRequest(request, response) {
    // Set the provider for logging purposes
    response.setProvider('provider_1');
 
    // Set the CNAME
    response.addCName('bar.foo.com');

    ...
}

addARecord(ip_address) - (DNS)

Adds the specified A record to the DNS response. addARecord can be called up to 8 times with different A record values specified to create the desired response.

addAAAARecord(ipv6_address) - (DNS)

Adds the specified AAAA record to the DNS response. addAAAARecord can be called up to 8 times with different AAAA record values specified to create the desired response.

function onRequest(request, response) {
    // To respond with multiple AAAA records, call response.addAAAARecord.
    // You may call it any number of times, but a good response should
    // only include up to 8 alternatives.
    response.addAAAARecord('2001:db8:0:0:0:0:2:1');
    response.addAAAARecord('2001:db8:0:0:0:0:2:2');

    ...
}

addProviderHost(provider_name, ip_or_hostname) - (HTTP)

Adds the provider name and specified host, IP or URL, to the HTTP response. addProviderHost can be called multiple times with a different provider and host specified to create the desired response.

function onRequest(request, response) {
    // Specify the provider alias and hostname
    response.addProviderHost('edgecast', 'http://www.example.edgecastcdn.net');

    // or

    // Specify an IP address
    response.addProviderHost('origin', '1.2.3.4');
 
    ...
}

addProviderHost(provider_name, ip_or_hostname, custom_data) - (HTTP)

Adds the provider name and specified host, IP or URL, and custom data to the HTTP response. addProviderHost can be called multiple times with a different provider, host and custom data specified to create the desired response. Custom data will be included in the provider response in the custom object.

function onRequest(request, response) {
    var custom = {
        'custom_key1': 'custom_val1',
        'custom_key2': 'custom_val2'
    };

    // Specify the provider alias, hostname and custom data
    response.addProviderHost('edgecast', 'http://www.example.edgecastcdn.net', custom);
 
    ...
}

The response generated will be:

{
    'providers': [
    {
        'custom': {
            'custom_key1': 'custom_val1',
            'custom_key2': 'custom_val2'
        },
        'host': 'http://www.example.edgecastcdn.net',
        'provider': 'edgecast'
    }]
}

respond(provider_name, ip_or_host) - (DNS)

Sets the A/AAAA/CNAME record for the response as well as the associated provider name used for logging purposes. IPv4 addresses should be in the form of 'a.b.c.d' where a, b, c, d are between 0 and 255 inclusive. IPv6 addresses should not be shortened.

function onRequest(request, response) {
    // Specify the provider alias and CNAME
    response.respond('edgecast', 'www.example.edgecastcdn.net');

    // or

    // Specify an A record by using an IP address
    response.respond('origin', '1.2.3.4');
 
    ...
}

respondEmpty() - (DNS)

Sets the A/CNAME record response to an empty value.

function onRequest(request, response) {
    // Specify an empty response
    response.respondEmpty();
    ...
}

setHeader(header_name, header_value) - (HTTP)

Adds the specified HTTP header value to the response.

function onRequest(request, response) {
    ...

    response.setHeader('X-Sample-Header', 'sample');

    ...
}

setProvider(provider_name)

Sets the provider for the decision so that it is logged and available for analysis.

function onRequest(request, response) {
    // Set the provider for logging purposes
    response.setProvider('provider_1');

    ...
}

setReasonCode(reason)

Sets the reason code for the decision so that it is logged and available for analysis.

function onRequest(request, response) {
    ...

    // Set the reason code for logging purposes
    response.setReasonCode('A');

    ...
}

setStatus(http_status_code) - (HTTP)

Sets the HTTP status code for the response. The status will default to 200 OK if no value is specified by the application and the application is processed correctly.

function onRequest(request, response) {
    ...

    // Set the status code, if not 200
    response.setStatus('403');

    ...
}

setTTL(dns_expiry) - (DNS)

Sets the expiry in seconds of the DNS response and overrides the default application TTL.

function onRequest(request, response) {
    ...
 
    response.setTTL(600);
}

Radar

Radar data is retrieved for the Openmix application with the request.getProbe() function.

Retrieving Data

function onRequest(request, response) {
    ...
    var avail = request.getProbe('avail');

    // avail = {
    //    'provider_1': { 'avail': 98.9 }, 
    //    'provider_3': { 'avail': 96.1 }
    // }  
}

The following probe values are available:

Data	Name	Format	Description
HTTP Availability	avail	Integer	Percentage of successful visits; returns a number from 0-100.
HTTP Response Time	http_rtt	Integer	Response time
HTTP Throughput	http_kbps	Integer	Throughput in KBPS for large objects, generally 100KB
HTTP Video Response Time	video_rtt	Integer	Response time of the delivered video chunks, if the Radar tag is configured to collect Video Playback data
HTTP Video Throughput	video_kbps	Integer	Throughput in KBPS of the delivered video chunks, if the Radar tag is configured to collect Video Playback data
DNS Static Proximity Distances	proximity_dist	Integer	Distances calculated as scores based on lat-long between platforms and lat-long of user

Data Format

The object returned from request.getProbe() contains the probe value for each provider. If a provider does not have the specified value, an empty object will be returned for the provider.

{
    'provider_1': {
        'http_rtt': 200
    },
    'provider_2': {
        'http_rtt': 199 
    },
    'provider_3': {
        'http_rtt': 198
    },
    'provider_4': {} // the value is not available for this provider
}

Fusion

Fusion data is retrieved for the Openmix application with the request.getData() function called with 'fusion' as the parameter. The format of the data returned by getData() is specific to the data feed setup in Fusion. The data could include CDN usage for the current month, APM monitoring data or custom data to be used in specialized routing applications.

Retrieving Data

function onRequest(request, response) {
    ...
    var fusion = request.getData('fusion');
    ...
}

Data Format

The format of the data returned by getData() depends on the data feed setup in Fusion. For example, It could be a JSON object from an APM product or a custom format defined by the user.

Here is an example of APM data:

fusion = {
    "fusion_cpu": {
        "unit": "%",
        "value": 2.92
    },
    "fusion_memory": {
        "unit": "%",
        "value": 95.1
    },
    "fusion_health": {
        "unit": "(0-5)",
        "value": "0"
    },
    "fusion_disk_io": {
        "unit": "%",
        "value": 0.03
    },
    "fusion_fullest_disk": {
        "unit": "%",
        "value": 28.9
    },
    "fusion_cpu_stolen": {
        "unit": "%",
        "value": 0.08
    }
}

or CDN usage data:

fusion = {
    "usage": {
        "unit": "GB",
        "value": "19563.67"
    },
    "bandwidth": {
        "unit": "Mbps",
        "value": "594.37"
    }
}

Sonar

Sonar is a synthetic availability check which can be enabled in the platform configuration. Once enabled, Sonar data is retrieved for the Openmix application with the request.getData() function called with 'sonar' as the parameter. The data is retrieved as a JSON object which can be parsed by the application.

Retrieving Data

function onRequest(request, response) {
    ...
    var sonar = request.getData('sonar');

    // sonar = {
    //     'provider_1': { 'avail': 1 },
    //     'provider_2': { 'avail': 0 }, 
    //     ...
    // }  
}

Data Format

The object returned from request.getData('sonar') contains the Sonar value for each provider. If a provider does not have Sonar enabled, the provider will not be included in the object. The value for the avialablity check will be an integer of value 0 for "down" or 1 for "up".

{
    'provider_name': {
        'avail': 1
    }, 
    ...
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Openmix API

Openmix JavaScript Application API

Application

Functions

Configuration

Functions

Request

Properties

Functions

Response

Functions

Radar

Retrieving Data

Data Format

Fusion

Retrieving Data

Data Format

Sonar

Retrieving Data

Data Format

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally