Basics

This page discusses some of the common elements used throughout the API.

Tasks

All API requests that create or update state (e.g. resource delegation) are handled asynchronously. The original request will yield a ‘task’ response, containing a task object URL that can be used to track the status of the request. For example, when creating a test object:

{
  "_links": {
    "api:tasks": {
      "href": "https://registry-testbed.apnic.net/nir-api/tasks/1"
    },
    "curies": [
      {
        "href": "https://registry-testbed.apnic.net/nir-api/docs/overview#{rel}",
        "name": "api",
        "templated": true
      }
    ]
  }
}

On fetching the task object:

{
  "id": 1,
  "taskStatus": "SUCCESSFUL",
  "_links": {
    "self": {
      "href": "https://registry-testbed.apnic.net/nir-api/tasks/1"
    },
    "related": {
      "href": "https://registry-testbed.apnic.net/nir-api/testObjects/1"
    }
  }
}

The user can then use the ‘related’ link to see the actual object that was created.

HAL

The API uses HAL for representing resources and relations. HAL provides a standard approach for including links (under the _links) element and nested objects (under the _embedded element) inside API responses. For example, a test object looks like so:

{
  "id": 1,
  "content": "test content",
  "_links": {
    "self": {
      "href": "https://registry-testbed.apnic.net/nir-api/testObjects/1"
    }
  }
}

One of the key features of HAL is the use of link relations. A link relation is a way of describing the type of a link. In HAL, link relations appear as keys within the _links element. For example, in the test object above, the ‘self’ link relation is used to describe a link that points to the object itself.

The registered set of link relations are available here. This API defines additional link relations, available here.

Idempotent requests

The API supports idempotency, for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. You can retry the request with the same idempotency key to guarantee that the request is not carried out more than once by the API.

To perform an idempotent request, provide an additional Idempotency-Key: $key header to the HTTP request. For example:

$ curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: asdf" \
  -X POST $BASE_URL/testObjects \
  --data-binary @- << EOF | jq
{
  "content": "test content"
}
EOF

{
  "_links": {
    "api:tasks": {
      "href": "https://registry-testbed.apnic.net/nir-api/tasks/1"
    },
    "curies": [
      {
        "href": "https://registry-testbed.apnic.net/nir-api/docs/overview#{rel}",
        "name": "api",
        "templated": true
      }
    ]
  }
}

On resubmitting the request with the same idempotency key, the system detects that the idempotency key has been seen before, and returns the same response as when the request was originally submitted (in this case, a pointer to a task object).

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. A simple approach is to use a new UUID for each client request.

Pagination

The API uses cursor-based pagination. When fetching a collection of objects, links to the next and previous pages in the set will be included in the response body. These link are indicated by the prev and next link relations. For example, for test objects (with a pageSize value of 2, to reduce the size of the response):

{
  "_embedded": {
    "api:testObjects": [
      {
        "id": 1,
        "content": "content 1",
        "_links": {
          "self": {
            "href": "https://registry-testbed.apnic.net/nir-api/testObjects/1"
          }
        }
      },
      {
        "id": 2,
        "content": "content 2",
        "_links": {
          "self": {
            "href": "https://registry-testbed.apnic.net/nir-api/testObjects/2"
          }
        }
      }
    ]
  },
  "_links": {
    "next": {
      "href": "https://registry-testbed.apnic.net/nir-api/testObjects?after=2&pageSize=2"
    },
    "prev": {
      "href": "https://registry-testbed.apnic.net/nir-api/testObjects?before=1&pageSize=2"
    },
    "self": {
      "href": "https://registry-testbed.apnic.net/nir-api/testObjects?pageSize=2"
    },
    "curies": [
      {
        "href": "https://registry-testbed.apnic.net/nir-api/docs/overview#{rel}",
        "name": "api",
        "templated": true
      }
    ]
  }
}

jCards

jCards are used to represent entity and subaccount contact details in the API. This is largely due to its use in RDAP: see RFC 7483, RFC8605.

NIR API jCard Profile

Because jCard is a complex specification and many of its features are not needed in this context, the API makes use of a jCard profile. The restrictions imposed by this profile are like so:

• Each jCard must contain at least one ‘fn’ property.

• Each jCard may contain one or more ‘title’ properties.

• Each jCard must contain a single ‘kind’ property.

• For the ‘kind’ property, the only values that may be used are ‘individual’, ‘org’, and ‘group’.

• Each jCard may contain one or more ‘adr’ properties.

• For ‘adr’ properties, a ‘label’ parameter must be included.

• Each jCard may contain one or more ‘tel’ properties.

• For ‘tel’ properties, a ‘type’ parameter must be included. The valid values for ‘type’ are ‘voice’ and ‘fax’.

• Each jCard may contain one or more ‘lang’ properties.

• Each jCard must contain at least one ‘email’ property.

• For ‘fn’, ‘title’, and ‘adr’ properties, the ‘language’ and ‘altid’ parameters may be used.

• No other properties or parameters may be used.

Alternate Language Representations

The JSON format for vCard data ‘jCard’ supports alternate language representations of properties such as ‘FN’ (formatted name), or ‘ADR’ (address).

This is via using a common ‘altid’ parameter value between two properties to “tag” the property instances as being alternative representations of the same logical property in conjunction with the ‘LANGUAGE’ property parameter.

The value of the LANGUAGE property parameter is a language tag as defined in Section 2 of [RFC5646].