-
Notifications
You must be signed in to change notification settings - Fork 15
Openmix HTTP API
Openmix intelligence is available via DNS and HTTP. The following is a description of how to call the Openmix HTTP API to retrieve optimize decisions.
Requests to the Openmix API can be made with a REST call:
http://hopx.cedexis.com/zones/<zone_id>/customers/<customer_id>/apps/<application_id>/decision
This will run the Openmix application and return a decision. The response is a JSON payload that contains a list of providers in ranked order.
The API can be tested with a tool such as libcurl. For example:
curl -v http://hopx.cedexis.com/zones/1/customers/0/apps/1/decision
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Mon, 22 Apr 2015 20:25:24 GMT
< Connection: keep-alive
< Content-Length: 177
<
{
"providers" : [
{
"provider" : "cdn1",
"host" : "cdn1.cdn1.net"
},
{
"provider" : "cloud2",
"host" : "cloud.cloud.com"
},
{
"provider" : "cdn2",
"host" : "cdn2.anothercdn.net"
}
]
}
The response format is a JSON object that can be parsed by the caller. It contains two properties: the providers array and the debug object.
{
"providers" : [
{
"provider" : "cdn1",
"host" : "cdn1.cdn1.net"
},
{
"provider" : "cloud2",
"host" : "cloud.cloud.com"
},
{
"provider" : "cdn2",
"host" : "cdn2.anothercdn.net"
}
],
"debug" : {
"region" : "IE-R-LEINSTER",
"country" : "IE",
"market" : "EU",
"caller_asn" : 16509,
"caller_ip_address" : "54.123.222.225",
"client_ip_address" : "54.123.222.225",
"duration" : 0,
"context_string" : "cdn1-http_rtt-mcra-48;cdn1-avail-mcra-94;cdn1-http_kbps-mcra-5014;cdn2-http_rtt-mcra-45;cdn2-avail-mcra-100;cdn2-http_kbps-mcra-41737;cloud-avail-m-100;cloud-http_rtt-m-41;cloud-avail-m-100;cloud-http_kbps-m-3748;",
"state" : "IE-S-DUBLIN",
"reason_code" : "A"
}
}
The request format is extensible to allow additional data to be returned along with each provider. If the Openmix application specifies custom data it will be included as a custom object containing key value pairs.
{
"providers" : [
{
"custom" " {
"key1" : "value1"
},
"provider" : "cdn1",
"host" : "cdn1.cdn1.net"
},
{
"custom" " {
"key1" : "value2"
},
"provider" : "cloud2",
"host" : "cloud.cloud.com"
},
{
"custom" " {
"key1" : "value3"
},
"provider" : "cdn2",
"host" : "cdn2.anothercdn.net"
}
]
}
The providers array contains a ranked list of the providers that can be used from the client. Each object in the array contains the following information:
| Name | Description |
|---|---|
| provider | The alias that was set for the platform when it was configured |
| host | The hostname or url that should be used to locate the content |
Information about the request can be optionally returned to the client in the debug property. Notice: The debug parameter should only be used in debug situation and not in production workflows.
The debug object contains the following properties:
| Name | Description |
|---|---|
| market | The geographic market for the IP used in the decision, most closely resembles continent |
| country | The country for the IP used in the decision. |
| region | The sub-country region for the IP used in the decision |
| state | The state for the IP used in the decision |
| caller_asn | The ASN number for the IP used in the decision |
| caller_ip | The IP of the client making the API call |
| client_ip | The IP used to make the decision, if the caller IP override is used |
| duration | The amount of time in milliseconds that it took to process the request |
| context_string | Radar scores for the platforms used in the application |
| reason_code | Application defined code denoting the type of decision made |
For more information about the geo values and other properties, please refer to the Openmix API.
The HTTP endpoints can be set to use basic authentication and require that a key be provided. This can be used to ensure that no other user agent is able to calls the Openmix application API endpoint.
Note: Use of secure keys requires calling the Openmix application API using TLS. This ensures that your credentials are not leaked to external intermediaries.
For information on turning on Secure Keys for an Openmix application, please refer to the Openmix topic in the User Guide.
Secured Openmix applications use Basic Authentication over TLS. Calling via plain HTTP will result in no response being returned. The key and secret are used as the username and password, respectively.
Usage:
curl -v -u test_key:d6276c72-64f6-4657-83a2-07136af3dcce https://hopx.cedexis.com/zones/1/customers/0/apps/1/decision
The HTTP endpoint has extended features over and above that of its DNS counterpart. These features provide greater visibility into the application response and to send additional data to the Openmix applications.
By default, the HTTP API uses the IP of the requesting client (i.e. the client that makes the TCP connection to the Openmix server) to geo-locate the request and make optimization decisions. The customer can override this behavior by appending an ip parameter to the query string. By specifying an IP address, it will be used as the client IP and the server will issue a response as though it received a request from the end-user at this IP. An IPv4 or IPv6 address can be specified.
| Name | Example |
|---|---|
| ip | ip=123.234.123.234 or ip=2001:db8:85a3:8d3:1319:8a2e:370:7348 |
Usage:
curl -v http://hopx.cedexis.com/zones/1/customers/0/apps/1/decision?ip=8.8.8.8
An additional parameter that can help with debugging is to add the debug query-string parameter. By applying this additional parameter the service will provide additional information on the client as well as information on the why the decision was made. For example:
| Name | Example |
|---|---|
| debug | debug |
Usage:
curl -v http://hopx.cedexis.com/zones/1/customers/0/apps/1/decision?debug
Example:
curl http://hopx.cedexis.com/zones/1/customers/0/apps/1/decision?debug
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Wed, 9 Sep 2015 20:25:24 GMT
< Connection: keep-alive
< Content-Length: 768
<
{
"providers" : [
{
"provider" : "cdn1",
"host" : "cdn1.cdn1.net"
},
{
"provider" : "cloud2",
"host" : "cloud.cloud.com"
},
{
"provider" : "cdn2",
"host" : "cdn2.anothercdn.net"
}
],
"debug" : {
"region" : "IE-R-LEINSTER",
"country" : "IE",
"market" : "EU",
"caller_asn" : 16509,
"caller_ip_address" : "54.123.222.225",
"client_ip_address" : "54.123.222.225",
"duration" : 0,
"context_string" : "cdn1-http_rtt-mcra-48;cdn1-avail-mcra-94;cdn1-http_kbps-mcra-5014;cdn2-http_rtt-mcra-45;cdn2-avail-mcra-100;cdn2-http_kbps-mcra-41737;cloud-avail-m-100;cloud-http_rtt-m-41;cloud-avail-m-100;cloud-http_kbps-m-3748;",
"state" : "IE-S-DUBLIN",
"reason_code" : "A"
}
}
In addition to the standard parameters, callers can pass in custom parameters via the query string that will be available to the Openmix applications. Data from the query parameters can be read in the application and custom behavior taken from the values.
Usage:
curl -v http://hopx.cedexis.com/zones/1/customers/0/apps/1/decision?custom_param=/path/to/my/file
Custom data can also be passed to the Openmix application via the request headers.
Headers can be read in the application and action taken for the request via the JavaScript code.
Usage:
curl -v -H "X-Custom: value" http://hopx.cedexis.com/zones/1/customers/0/apps/1/decision