NS1 status

Articles in this section

Configuring Pulsar decisions over HTTP

  • Updated
Follow

The Pulsar decision service allows interaction with Pulsar over HTTP—giving customers the same decision-making power as the DNS mechanism. When queried, the decision service via HTTP returns an ordered list of optimal answers, making it compatible with client integrations and CDN token authentication.

Request

To generate a decision for a single-named record, issue a request to:

https://api.ns1decisions.net/v1/decision?parameters

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 platform (ex. pulsar.example.com). Note that this record does not need to be delegated to NS1 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

Authentication

The Pulsar decision service uses the same API key and authentication mechanism as the NS1 platform API (see https://ns1.com/api). Create an API key in the NS1 portal to use in the X-NSONE-KEY request header.

Source address for decisions

Pulsar decisions are made based on the geographic and network location information of your source IP address. The Pulsar 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: 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.

Successful response

Successful responses share a common format:

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

where

  • resources

    An array containing an object for each resource output by Pulsar's decision process. The particular format of each resource varies by type; these are described below.

  • 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
}

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 the NS1 platform.

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 is not authoritative for it, or the request is refused.

Ensure the named record is configured correctly on the NS1 platform.

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’s platform.

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.

Related articles