Manage PID through an API

Resolving a PID

To be able to manage PIDs through an API, you need an authorization key, either for the sandbox or your own PID prefix.

PID is passed to Resolver as a specific URL. Normally the API is accessed through commands like curl or directly from a browser using JavaScript.

Using curl you can do:

$ curl -s hdl.handle.net/api/handles/PREFIX/SUFFIX

as in:

$ curl -s hdl.handle.net/api/handles/21.17101/EPIC_HEALHCHECK

The response is a JSON object containing the same information obtained from a resolver (visible by adding ?noresolve at the end of the resolver URL). Here is an example (pretty printed by appending ?pretty=true to the resolver URL):

$ curl -s 'https://hdl.handle.net/api/handles/21.T17999/836c3c76-6b25-11e9-a684-80000208fe80?pretty=true'
{
  "responseCode": 1,
  "handle": "21.T17999/836c3c76-6b25-11e9-a684-80000208fe80",
  "values": [
    {
      "index": 1,
      "type": "URL",
      "data": {
        "format": "string",
        "value": "https://object.cscs.ch/v1/...\n"
      },
      "ttl": 86400,
      "timestamp": "2019-04-30T08:54:10Z"
    },
    {
      "index": 10,
      "type": "Description",
      "data": {
        "format": "string",
        "value": "my new results"
      },
      "ttl": 86400,
      "timestamp": "2019-04-30T08:54:10Z"
    },
    {
      "index": 100,
      "type": "HS_ADMIN",
      "data": {
        "format": "admin",
        "value": {
          "handle": "21.T17999/mvalle",
          "index": 300,
          "permissions": "011111110011"
        }
      },
      "ttl": 86400,
      "timestamp": "2019-04-30T08:54:10Z"
    }
  ]
}

Create and manage PIDs

The procedure to create or manage PIDs through the API is a little more complex because you have to authenticate yourself through the API.

Create Keys and Certificate used in CLI

Note that the hdl tools that are used below, come precompiled for linux and windows with the handle software. In the following command lines, the operation uses the fictitious user "piduser" that owns the Prefix "21.T17998"

The first step is to convert the binary private key (received when registered for the service) into a pem file:

hdl-convert-key 21.T17998_piduser_300_privkey.bin -o 21.T17998_piduser_300_privkey.pem

Generate a Certificate file valid for ten years

openssl req -pubkey -x509 -new -sha256 -subj "/CN=300:21.T17998\/piduser" -days 3652 \
    -key 21.T17998_piduser_300_privkey.pem -out 21.T17998_piduser_300_certificate_and_publickey

Remove the public key from the certificate:

openssl x509 -inform PEM -in 21.T17998_piduser_300_certificate_and_publickey -out 21.T17998_piduser_300_certificate_pnly.pem

Create and Manage a PID using CURL

A data file is needed to create or change the PID. You edit it to change the URL and the user name and prefix. In the example the file is called pid.json:

[
    {
      "index": 1,
      "type": "URL",
      "data": {
        "format": "string",
        "value": "<your URL>"
      }
    },
    {
      "index": 100,
      "type": "HS_ADMIN",
      "data": {
        "format": "admin",
        "value": {
          "handle": "21.T17998/piduser",
          "index": 300,
          "permissions": "011111110011"
        }
      }
    }
]

Then pass all these info to the API after selecting an appropriate suffix.

curl --insecure --key 21.T17998_piduser_300_privkey.pem --cert 21.T17998_piduser_300_certificate_only.pem \
     -H 'Authorization: Handle clientCert="true"' -H "content-type:application/json" \
     --data-binary "@pid.json" -X PUT handle01.cscs.ch/api/handles/21.T17998/my-first-example

For editing and modifying an existing PID, the procedure is the same.

Note that the host is no longer the top level one, but the CSCS one.