Decisions over HTTP

With IBM® NS1 Connect®, you can enable RUM data decisioning over HTTP, providing the same decision-making power as the DNS mechanism. When a record is queried, the decision service via HTTP returns an ordered list of optimal answers, making it compatible with multi-CDN client integrations, content steering, and CDN token authentication.

Request a decision for a record

To generate a decision for a single-named record, issue a request to: https://api.ns1decisions.net/v1/decision?


Request parameter	Type	Description
`name`	string	(Required) Name of the DNS record you want to query. This is the fully qualified domain name of any record configured on the NS1 Connect platform (for example, `pulsar.example.com`). Note that this record does not need to be delegated to NS1 Connect in public registrars.
`type`	string	(Optional) Record type. The default value is CNAME. All possible values are CNAME, TXT, SRV.
`cedexis-format`	string	If you use this parameter, specifying any value ensures that results will be in Cedexis format.

For example:

https://api.ns1decisions.net/v1/decision?name=pulsar.example.com&type=TXT

You can authenticate the request using a valid NS1 Connect API key in the X-NSONE-KEY request header.

Source address for decisions

RUM-based traffic steering decisions are made based on the geographic and network location information of your source IP address. The decision service selects the most appropriate source address by choosing the first specified value among the following options:

If defined, the client address from the X-Forwarded-For request header (optional) is used.
If no X-Forwarded-For address is defined, the client's source IP address is used.

For example:

curl -s -H "X-NSONE-Key: $NSONE_API_KEY" -H "X-Forwarded-For:192.0.2.1" "https://api.ns1decisions.net/v1/decision?name=pulsar.example.com&type=TXT"

Response

All responses (success and error) are returned as Content-Type: application/json; charset=utf-8.

Example of a successful response

Successful responses share a common format:

{
"resources": [],
"ttl": 0
}

resources - An array containing an object for each resource output by the decision process. The particular format of each resource varies by type.
ttl - An integer value in seconds indicating how long the objects in the resources array are valid for.

Examples of resource payloads:

CNAME and TXT types response

{
   "resources": [
        {
             "label": "a.foo.com"
        },
        {
             "label": "b.bar.com"
        },
        {
             "label": "c.baz.com"
        }
   ],
   "ttl": 60
}

SRV type response

{
   "resources": [
        {
             "label": "a.foo.com",
             "priority": 10,
             "weight": 11,
             "port": 12000
        },
        {
             "label": "b.bar.com",
             "priority": 20,
             "weight": 2,
             "port": 3000
        }
   ],
   "ttl": 3600
}

Example of an error response

Error responses share a common format:

{
   "error": {
        "<message>": "resource not found"
   }
}

where <message> is a user-friendly description of the error condition. Technical reasons for failure are conveyed via HTTP status codes.

HTTP status codes


Code	Meaning	Recommended action
200	Successful transaction.	None.
300	The name exists, but the type does not.	Include the type parameter for which the name exists on NS1 Connect.
400	Invalid data in the request.	Either the URL parameter name or value is invalid.
401	No authorization provided.	Include the proper API key header with your requests.
404	Either the `name` does not exist, NS1 Connect is not authoritative for it, or the request is refused.	Ensure the named record is configured correctly on NS1 Connect.
405	Unsupported HTTP method.	Use only supported methods.
418	The request was correct and handled successfully but resulted in a semantic error.	Ensure the named record is correctly configured on NS1 Connect.
500	The request was correct and handled successfully but resulted in corrupt or invalid data.	This is a transient error condition. Retry the same request.
503	Exhausted attempts at servicing request.	Retry the same request.

Headers

For successful transactions, HTTP Cache-Control headers are set according to the record's TTL. All responses are returned set for private caches with max-age equal to the record's TTL.