Openmix API

Damian edited this page Oct 13, 2017 · 35 revisions

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);
}

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('*');

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

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
    }, 
    ...
}