PCC-174: [API] Create a Handle

[irinaskop]

This PR adds support for creating a Handle under an existing PCC Prefix.

A user can create a Handle by providing:

• the Handle suffix
• the Handle service URL
• the Handle service token
• the Handle type/value pairs

The Prefix is resolved from the PCC database using its internal PCC ID.

The authenticated PCC user's unique identifier is used when constructing the required HS_ADMIN Handle value.

Endpoint

POST /api/v1/prefixes/{prefix-id}/handles

Example request:

{
  "suffix": "irina-test-24",
  "serviceUrl": "https://hdl.grnet.gr:8001",
  "token": "<HANDLE_SERVICE_TOKEN>",
  "values": [
    {
      "type": "URL",
      "value": "https://www.grnet.gr"
    },
    {
      "type": "title",
      "value": "Irina Test Handle"
    },
    {
      "type": "description",
      "value": "Handle created through PCC"
    }
  ]
}

Example successful response:

{
  "handle": "21.T15999/irina-test-24",
  "values": [
    {
      "type": "URL",
      "value": "https://www.grnet.gr"
    },
    {
      "type": "title",
      "value": "Irina Test Handle"
    },
    {
      "type": "description",
      "value": "Handle created through PCC"
    }
  ]
}

Handle service request

PCC transforms the user-provided values to the structure expected by the underlying Handle service.

Value indexes are generated automatically starting from 1.

For example:

{
  "type": "URL",
  "value": "https://www.grnet.gr"
}

is sent to the Handle service as:

{
  "index": 1,
  "type": "URL",
  "data": {
    "format": "string",
    "value": "https://www.grnet.gr"
  }
}

The required HS_ADMIN value is appended automatically.

Its Handle reference is constructed using the selected Prefix and the authenticated PCC user's unique identifier.

Error handling

Errors returned by the Handle service are translated to the PCC API response format.

Example:

{
  "code": 400,
  "message": "That prefix doesn't live here"
}

The downstream HTTP status, Handle response code, Handle and message are logged for troubleshooting.

Handle service tokens are not logged.

TLS

The Handle service is accessed over HTTPS.

The Java runtime used by PCC must trust the CA chain of the configured Handle service. For hdl.grnet.gr, this includes the HARICA TLS RSA Root CA 2021.

Local testing

For an end-to-end test against the real Handle service, create a Prefix with the name 21.T15999 using the existing PCC Create Prefix endpoint.

Example request:

{
  "name": "21.T15999",
  "owner": "GRNET",
  "used_by": "GRNET",
  "contract_end": "2028-07-22",
  "status": 0,
  "service_id": 1,
  "domain_id": 1,
  "provider_id": 1,
  "resolvable": true,
  "contact_name": "John Doe",
  "contact_email": "contact@example.org",
  "contract_type_id": 5,
  "lookup_service_type_id": 1
}

Use the generated PCC Prefix ID to call:

POST /api/v1/prefixes/{prefix-id}/handles

Use:

• serviceUrl: https://hdl.grnet.gr:8001
• token: a valid Handle service token
• a new suffix for each test

Example:

{
  "suffix": "review-test-1",
  "serviceUrl": "https://hdl.grnet.gr:8001",
  "token": "<HANDLE_SERVICE_TOKEN>",
  "values": [
    {
      "type": "URL",
      "value": "https://www.grnet.gr"
    }
  ]
}

The real Handle service token is provided separately to the reviewer.