Additional Metadata filter

The example POST command below edits a record by configuring two answers (both of which require additional metadata), then applying the Additional Metadata filter to the record. The meta section specifies the additional_metadata key-value pairs "foo": "bar" and "baz": "blarg" for answer1.test.com and "red": "blue" for answer2.test.com. The filters section specifies the additional_metadata filter, which is applied to the entire record.

curl -X POST -H 'X-NSONE-Key: $API_KEY' \
https://api.nsone.net/v1/zones/example.com/test.example.com/CNAME \
-d '{
  "answers": [
    {
      "answer": [
        "answer1.test.com"
      ],
      "meta": {
        "additional_metadata": [
          {
            "foo": "bar",
            "baz": "blarg"
          }
        ]
      }
    },
    {
      "answer": [
        "answer2.test.com"
      ],
      "meta": {
        "additional_metadata": [
          {
            "red": "blue"
          }
        ]
      }
    }
  ],
  "filters": [
    {
      "filter": "additional_metadata",
      "config": {}
    }
  ]
}'

The resulting DNS response based on the record above should match this:

$ dig @dns1.p01.nsone.net test.example.com

; <<>> DiG 9.10.6 <<>> @dns1.p01.nsone.net test.example.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1750
;; flags: qr aa rd; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 5
;; WARNING: recursion requested but not available

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
;; QUESTION SECTION:
;test.example.com.              IN      CNAME

;; ANSWER SECTION:
test.example.com.       3600    IN      CNAME   answer1.test.com.
test.example.com.       3600    IN      CNAME   answer2.test.com.

;; ADDITIONAL SECTION:
0.meta._ns1.            0       IN      TXT     "baz=blarg"
0.meta._ns1.            0       IN      TXT     "foo=bar"
1.meta._ns1.            0       IN      TXT     "red=blue"

;; Query time: 13 msec
;; SERVER: 198.51.44.1#53(198.51.44.1)
;; WHEN: Thu Sep 16 15:54:04 GMT 2021
;; MSG SIZE  rcvd: 189

Note the ADDITIONAL section includes a list of TXT records corresponding to the additional metadata key-value pairs applied to the DNS answers. Note the order of the TXT records corresponds to the order of eligible answers after being processed by the NS1 Filter Chain. For example, the first two TXT records listed correspond to the first DNS answer (answer1.test.com) and contain the 0.meta._ns1. domain name. The third TXT record corresponds to the second DNS answer (answer2.test.com) and contains the 1.meta._ns1 postfix. This postfix is applied to avoid interoperability issues. As such, the Additional Metadata filter must be placed at the end of the Filter Chain configuration to avoid breaking the association between the order of the TXT records and their corresponding answers.

Pulsar customers who have configured decisions over HTTP can specify additional metadata records and apply the filter to return the metadata in the JSON response under the meta section. For example (replacing $API_KEY accordingly):

$ curl -s -H "X-NSONE-Key: $API_KEY" -H "X-Forwarded-For:192.0.2.1" 'https://rt.ns1p.net/v1/decision?name=test.example.com&type=CNAME' | jq .
{
  "resources": [
    {
      "label": "answer1.test.com",
      "meta": {
        "baz": "blarg",
        "foo": "bar"
      }
    },
    {
      "label": "answer2.test.com",
      "meta": {
        "red": "blue"
      }
    }
  ],
  "ttl": 3600
}