AnswerX RKS API

The AnswerX API lets you interact with table data using two different endpoints whose responses are formatted identically. One assumes you know the unique service instance identifier, and the other requires only the contract identifier and product name, such as managed or cloud.

API operations specify table rows with a unique key parameter, which matches the value in the first column of the row. String values must be double-quoted then URL-encoded, for example %22KEY%22.

POST operations that reference a new key add rows to the table, otherwise they modify existing rows.

DELETE operations remove existing rows. The key is required for DELETE. Deletions are always per-row, never the entire table.

The action and table_type parameters do not apply to POST or DELETE operations. They only apply to the GET operations enumerated below (dump, dump-data-only, schema, and subscribe). All GET operations besides those four are per-row and require a key parameter but not an action or table_type.

  • dump: Reports the full contents of a table, either for a static, dynamic, or rtt table in read-only format. It does not modify a table’s contents. Leave out the ‘key’ parameter as it refers to a specific table row. For static tables, the schema is included. If the table_type is rtt, you must include &table_type=rtt in the URL.

  • dump-data-only: Reports the full contents of a table as above, but lists the data in a minimal text format. Leave out the ‘key’ parameter as it refers to a specific table row.

  • schema: Generates a description of the requested table data. Note that this data does not follow the more formal XML or JSON schema format.

  • subscribe: Generates table metadata up to the current sync point, usually equivalent to the table schema. This only applies to dynamic table types.

The key required for POST, DELETE, and per-row GET operations. For other operations, do not specify a key since the operation returns the whole table (the key is not omitted but not applicable because the operation returns the entire table).

The table_type parameter is only needed if calling dump or dump-data-only on a dynamic table. In those cases, specify table_type=dynamic or table_type=rtt. You can specify table_type=static but static is the default, so it is optional. These are the only cases where table_type is needed. This parameter does not work with POST or DELETE operations.

The table_type parameter is only needed if calling “dump” or “dump-data-only” on a dynamic table. In those cases, specify table_type=dynamic or table_type=rtt. You can specify table_type=static but static is the default, so it is optional. These are the only cases where table_type is needed.

See the Get Row or Table by Service Instance or Get Row or Table by Product Type operations for samples of this alternative output.

API Summary

Operation Method Endpoint
Service Instances
Get Row or Table by Service Instance GET /recursive-dns-db/v1/service-instances/{serviceInstanceId}/tables/{tableName}{?key,action,table_type}
Add or Update Row by Service Instance POST /recursive-dns-db/v1/service-instances/{serviceInstanceId}/tables/{tableName}{?key}
Remove Row by Service Instance DELETE /recursive-dns-db/v1/service-instances/{serviceInstanceId}/tables/{tableName}{?key}
Product Types
Get Row or Table by Product Type GET /recursive-dns-db/v1/product-types/{productType}/contracts/{contractId}/recursive-db/tables/{tableName}{?key,action,table_type}
Add or Update Row by Product Type POST /recursive-dns-db/v1/product-types/{productType}/contracts/{contractId}/recursive-db/tables/{tableName}{?key}
Remove Row by Product Type DELETE /recursive-dns-db/v1/product-types/{productType}/contracts/{contractId}/recursive-db/tables/{tableName}{?key}

Get Row or Table by Service Instance

This operation gets data for a row with a unique service instance ID. For rows it works on both static and RTT tables. If no rows have a key column matching this string, an error will be returned. If the key column is of type STRING, then the key must be enclosed in URL-encoded double quotes (%22key%22).

GET /recursive-dns-db/v1/service-instances/{serviceInstanceId}/tables/{tableName}{?key,action,table_type}

Example: /recursive-dns-db/v1/service-instances/8739485/tables/TableData–1?key=%22127.0.0.1%22&action=schema&table_type=rtt

Parameter Type Sample Description
Required
key String "127.0.0.1" The value of the key column to access. If the key column is a string, it must be wrapped with URL-encoded double quotes, such as %22key%22.
serviceInstanceId Integer 8739485 The service instance ID.
tableName String TableData-1 The table to be queried.
Optional
action String schema The action taking place. The parameters are dump to remove an entire table, dump-data-only to remove only the data found in a table, subscribe to return table metadata up to the current sync point with a service instance ID, or schema to describe the table’s structure. Used with the GET and POST operations.
table_type String rtt Table types may be static, dynamic, or rtt. You can set this parameter to static. The default value is rtt.

Status 200 application/xml

Response:

<Row>
    <Key>127.0.0.1</Key>
    <Columns>
        <Column>
            <Value>127.0.0.1</Value>
        </Column>
        <Column>
            <Value>Utah</Value>
        </Column>
    </Columns>
</Row>

Status 200 application/json

Response:

{
    "Key": "127.0.0.1",
    "Columns": [
        { "Value": "Utah" },
        { "Value": "127.0.0.1" }
    ]
}

The following shows the alternate response format when the action is set to schema or subscribe. Each field’s Name is a valid key with which to access a table row.

<Schema>
    <Field>
        <Name>HostIP</Name>
        <Type>CIDR</Type>
    </Field>
    <Field>
        <Name>SubscriberID</Name>
        <Type>STRING</Type>
    </Field>
</Schema>

The following shows the alternate response format when the action is set to dump. The MetaData section and each Field contain lines of key/value pairs rather than structured XML. The trailing lines after the MetaData section represent the table’s raw data separately available when the action is dump-data-only.

<Schema>
    <Field>
        Name: MyKey
        Type: STRING
    </Field>
    <Field>
        Name: v4Mask
        Type: UINT64
    </Field>
    <Field>
        Name: v6Mask
        Type: UINT64
    </Field>
    <Field>
        Name: MyVal
        Type: STRING
    </Field>
    <Field>
        Name: MyCidr
        Type: CIDR
    </Field>
</Schema>

<MetaData>
    TableType: INDEXED
    TableVersion: 6241959731729006595
</MetaData>
    "Michelangelo" 32 128 "Donatello" 5.6.7.8/32
    "Raphael" 24 96 "Leonardo" 127.0.0.1/32

Add or Update Row by Service Instance

The request must specify the row’s data, formatted as XML or JSON. The optional Expiry data member is a time interval in seconds after which the row expires: if no expiry is given, the row does not expire. This method only applies to RTT tables.

The key column is matched against the leftmost column in the table. If it matches an existing row, that row is updated. Otherwise, a new row is added. Note that key is considered to be the value of the leftmost row: thus, the XML or JSON you submit in the body of your request should not contain a field for the leftmost key column: only for the subsequent columns.

In the following example the table is assumed to have two columns. The first one is updated by using the key field, and the second one is a string column whose new value will be Arizona.

POST /recursive-dns-db/v1/service-instances/{serviceInstanceId}/tables/{tableName}{?key}

Example: /recursive-dns-db/v1/service-instances/8739485/tables/TableData–1?key=%22127.0.0.1%22

Content-Type: application/xml

Request:

<Row>
    <Columns>
        <Column>
            <Value>Arizona</Value>
            <Type>STRING</Type>
        </Column>
    </Columns>
    <Expiry>60</Expiry>
</Row>

TBD /recursive-dns-db/v1/service-instances/{serviceInstanceId}/tables/{tableName}{?key}

Example: /recursive-dns-db/v1/service-instances/8739485/tables/TableData–1?key=%22127.0.0.1%22

Content-Type: application/json

Request:

{
    "Expiry": 60,
    "Columns": [
        {
            "Value": "Arizona",
            "Type": "STRING"
        }
    ]
}

Parameter Type Sample Description
Required
key String "127.0.0.1" The value of the key column to access. If the key column is a string, it must be wrapped with URL-encoded double quotes, such as %22key%22.
serviceInstanceId Integer 8739485 The service instance ID.
tableName String TableData-1 The table to be queried.

Status 204

Remove Row by Service Instance

This operation lets you delete a row from a table with a service instance ID. It only applies to RTT tables. The row to be deleted must have a leftmost key column whose value matches key.

DELETE /recursive-dns-db/v1/service-instances/{serviceInstanceId}/tables/{tableName}{?key}

Example: /recursive-dns-db/v1/service-instances/8739485/tables/TableData–1?key=%22127.0.0.1%22

Parameter Type Sample Description
Required
key String "127.0.0.1" The value of the key column to access. If the key column is a string, it must be wrapped with URL-encoded double quotes, such as %22key%22.
serviceInstanceId Integer 8739485 The service instance ID.
tableName String TableData-1 The table to be queried.

Status 204

Get Row or Table by Product Type

This operation gets data for a row with a unique product name and contract ID. For rows it works on both static and RTT tables. If no rows have a key column matching this string, an error will be returned. If the key column is of type STRING, then the key must be enclosed in URL-encoded double quotes (%22key%22).

GET /recursive-dns-db/v1/product-types/{productType}/contracts/{contractId}/recursive-db/tables/{tableName}{?key,action,table_type}

Example: /recursive-dns-db/v1/product-types/managed/contracts/ctr_1–1TJZH5/recursive-db/tables/TableData–1?key=%22127.0.0.1%22&action=schema&table_type=rtt

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 The contract ID.
key String "127.0.0.1" The value of the key column in the row to be returned. If no rows have a key column matching this string, an error will be returned. If the key column is of type STRING, then the key must be enclosed in URL-encoded double quotes (%22key%22).
productType String managed The type of RKS.
tableName String TableData-1 The table to be queried.
Optional
action String schema The action taking place in an operation. The parameters are dump to remove an entire table, dump-data-only to remove only the data found in a table, subscribe to return table metadata up to the current sync point with a service instance ID, or schema to describe the table’s structure.
table_type String rtt Table types may be static, dynamic, or rtt. You can set this parameter to static. The default value is rtt.

Status 200 application/xml

Response:

<Row>
    <Key>127.0.0.1</Key>
    <Columns>
        <Column>
            <Value>127.0.0.1</Value>
        </Column>
        <Column>
            <Value>Utah</Value>
        </Column>
    </Columns>
</Row>

Status 200 application/json

Response:

{
    "Key": "127.0.0.1",
    "Columns": [
        { "Value": "Utah" },
        { "Value": "127.0.0.1" }
    ]
}

The following shows the alternate response format when the action is set to schema or subscribe. Each field’s Name is a valid key with which to access a table row.

<Schema>
    <Field>
        <Name>HostIP</Name>
        <Type>CIDR</Type>
    </Field>
    <Field>
        <Name>SubscriberID</Name>
        <Type>STRING</Type>
    </Field>
</Schema>

The following shows the alternate response format when the action is set to dump. The MetaData section and each Field contain lines of key/value pairs rather than structured XML. The trailing lines after the MetaData section represent the table’s raw data separately available when the action is dump-data-only.

<Schema>
    <Field>
        Name: MyKey
        Type: STRING
    </Field>
    <Field>
        Name: v4Mask
        Type: UINT64
    </Field>
    <Field>
        Name: v6Mask
        Type: UINT64
    </Field>
    <Field>
        Name: MyVal
        Type: STRING
    </Field>
    <Field>
        Name: MyCidr
        Type: CIDR
    </Field>
</Schema>

<MetaData>
    TableType: INDEXED
    TableVersion: 6241959731729006595
</MetaData>
    "Michelangelo" 32 128 "Donatello" 5.6.7.8/32
    "Raphael" 24 96 "Leonardo" 127.0.0.1/32

Add or Update Row by Product Type

This operation allows you to add or update a row in a table with a product name and contract ID. The optional Expiry data member is a time interval in seconds after which the row expires: if no expiry is given, the row does not expire. This method only applies to RTT tables.

The data in your request should contain the row to be updated or added, in either XML or JSON format (see the following examples). If your table only consists of one row, then the message body for your submit would not contain any columns, since the key field is used as the leftmost column value (see below for more on this).

The key column is matched against the leftmost column in the table. If it matches an existing row, that row is updated. Otherwise, a new row is added. Note that key is considered to be the value of the leftmost row: thus, the XML or JSON you submit in the body of your request should not contain a field for the leftmost key column: only for the subsequent columns.

In the following example the table is assumed to have two columns. The first one is updated by using the key field, and the second one is a string column whose new value will be Arizona.

POST /recursive-dns-db/v1/product-types/{productType}/contracts/{contractId}/recursive-db/tables/{tableName}{?key}

Example: /recursive-dns-db/v1/product-types/managed/contracts/ctr_1–1TJZH5/recursive-db/tables/TableData–1?key=%22127.0.0.1%22

Content-Type: application/xml

Request:

<Row>
    <Columns>
        <Column>
            <Value>Arizona</Value>
            <Type>STRING</Type>
        </Column>
    </Columns>
    <Expiry>60</Expiry>
</Row>

TBD /recursive-dns-db/v1/product-types/{productType}/contracts/{contractId}/recursive-db/tables/{tableName}{?key}

Example: /recursive-dns-db/v1/product-types/managed/contracts/ctr_1–1TJZH5/recursive-db/tables/TableData–1?key=%22127.0.0.1%22&action=schema&table_type=rtt

Content-Type: application/json

Request:

{
    "Expiry": 60,
    "Columns": [
        {
            "Value": "Arizona",
            "Type": "STRING"
        }
    ]
}

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 The contract ID.
key String "127.0.0.1" The value of the key column in the row to be returned. If no rows have a key column matching this string, an error will be returned. If the key column is of type STRING, then the key must be enclosed in URL-encoded double quotes (%22key%22).
productType String managed The type of RKS.
tableName String TableData-1 The table to be queried.

Status 204

Remove Row by Product Type

This operation lets you delete a row from a table with a product name and contract ID. It only applies to RTT tables. The row to be deleted must have a key column (leftmost column) whose value matches key.

DELETE /recursive-dns-db/v1/product-types/{productType}/contracts/{contractId}/recursive-db/tables/{tableName}{?key}

Example: /recursive-dns-db/v1/product-types/managed/contracts/ctr_1–1TJZH5/recursive-db/tables/TableData–1?key=%22127.0.0.1%22

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 The contract ID.
key String "127.0.0.1" The value of the key column in the row to be returned. If no rows have a key column matching this string, an error will be returned. If the key column is of type STRING, then the key must be enclosed in URL-encoded double quotes (%22key%22).
productType String managed The type of RKS.
tableName String TableData-1 The table to be queried.

Status 204


Last modified: 12/12/2016