Create, Update and Delete Entity Objects

An ‘entity’ is a contact point, and may represent a specific person or an organizational function. An entity is generally associated with a subaccount. The main purpose of entities in the API is to provide contact details for delegations in Whois/RDAP. The API supports the general management of entities (create, update, delete).

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.

Create an entity object

To create a new entity object:

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

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

# Create a new entity object.
$ curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X POST $BASE_URL/entities \
  --data-binary @- << EOF | jq
{
    "jcard": [
        "vcard",
        [
            [ "version", {}, "text", "4.0" ],
            [ "kind", {}, "text", "group" ],
            [ "fn", {}, "text", "Entity Role" ],
            [ "adr", { "cc": "US", "label": "123 Main Street\nAny Town\nCA 91921-1234" },
              "text", [ "", "", "123 Main Street", "Any Town", "CA", "91921-1234", "" ] ],
            [ "email", {}, "text", "entity-role@example.org" ],
            [ "tel", { "type": "voice" }, "text", "+61-123456" ],
            [ "tel", { "type": "fax" }, "text", "+61-123456" ]
        ]
    ]
}
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
      }
    ]
  }
}

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/entities/1"
    }
  }
}

To fetch the entity object itself:

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

{
  "id": 1,
  "jcard": [
    "vcard",
    [
      [
        "version",
        {},
        "text",
        "4.0"
      ],
      [
        "kind",
        {},
        "text",
        "group"
      ],
      [
        "fn",
        {},
        "text",
        "Entity Role"
      ],
      [
        "adr",
        {
          "cc": "US",
          "label": "123 Main Street\nAny Town\nCA 91921-1234"
        },
        "text",
        [
          "",
          "",
          "123 Main Street",
          "Any Town",
          "CA",
          "91921-1234",
          ""
        ]
      ],
      [
        "email",
        {},
        "text",
        "entity-role@example.org"
      ],
      [
        "tel",
        {
          "type": "voice"
        },
        "text",
        [
          "+61-123456"
        ]
      ],
      [
        "tel",
        {
          "type": "fax"
        },
        "text",
        [
          "+61-123456"
        ]
      ]
    ]
  ],
  "externalId": null,
  "createdInWhois": false,
  "_links": {
    "self": {
      "href": "https://registry-testbed.apnic.net/nir-api/entities/1"
    }
  }
}

Update an entity object

The example belows fetches the entity object and updates the email attribute of the jCard from “test@test.net” to “new-test@test.net”. Then, finally submit a PUT request using the change.

$ export UPDATE=$(curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  $BASE_URL/entities/1 | sed 's/test@test.net/new-test@test.net/g')

$ echo $UPDATE | curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT $BASE_URL/entities/1 \
  --data-binary @- | jq

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

Delete the entity object

Finally, deleting the entity object:

$ curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X DELETE $BASE_URL/entities/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
      }
    ]
  }
}