Experiment With The API Using Test Objects

The API supports ‘test objects’, which can be used to try out basic create/update/delete operations without affecting any resource management information. This tutorial walks through this process. All operations in the API follow the model described in this tutorial, so it’s useful to review this tutorial first before looking at the other material.

This tutorial assumes that you have an access token. If you do not have an access token, see Authentication for details on how to get one.

To create a new test object:

# Configure the access token.
$ export TOKEN=$access_token

# Configure the API base URL.
$ export BASE_URL=https://registry-testbed.apnic.net/nir-api

# Generate UUID
$ export UUID=$(uuidgen)

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

This will produce a task response:

{
  "_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
      }
    ]
  }
}

The task object is used to keep track of a given request. It includes details on the status of the task, and (if the task was completed successfully) a link to the resulting object (see ‘related’).

To fetch the task object:

$ curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  $BASE_URL/tasks/1 | jq

{
  "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"
    }
  }
}

To fetch the test object itself:

$ curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  $BASE_URL/testObjects/1 | jq

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

To edit an existing test object:

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

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

The task object looks like so:

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

Fetching the test object shows the update:

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

Finally, deleting the test object:

$ curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X DELETE $BASE_URL/testObjects/1 | jq

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

On fetching the task, note that there is no ‘related’ link, since the object has now been deleted.

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