SURF User Knowledge Base
Space shortcuts
Page tree

There are several ways to interact with the Handle REST API.

With the API you can:

  • Mint or create new handles
  • Modify existing handles by changing the reference location or adding or removing additional metadata entries
  • Delete handles

This guide explains on how to use the API using PHP.

Sessions

Handles can be created one by one using independent API calls, or you can initiate a session before making subsequent calls. A session has the advantage that authorisation only needs to be done once at the time of creation of that session. Successive API calls after a session has been started will then be much faster than when for each call the authorisation needs to be checked.

Please refer to the equivalent bash guide to learn how to employ sessions in managing your handles.

Single handle creation using PHP

A simple script is shown below.

Use the right port

Always make sure to use the right port in your URL! For test prefixes use port 8003 and for production prefixes use port 8000 up to 8007, depending on what has been communicated to you.

<?php

$handleServerUrl = "https://epic-pid.storage.surfsara.nl";

/**
 #### modify following lines. assuming 310:<PREFIX>/USER01 for authentication
 */
$port            = 8003;
$prefix          = "841";
$certificateOnly = '<your-path>/365_841_ADMIN_certificate_only.pem';
$privateKey      = '<your-path>/365_841_ADMIN_privkey.pem';
$suffix          = "0001e2a0-fb8f-11df-9e4d-523bc2e286e2";
/**
 #### end modify lines
 */

$url       = "https://www.test.com";

$handleUrl = "${handleServerUrl}:${port}/api/handles/${prefix}/${suffix}";

echo "Creating handle: ${handleUrl}\n\n";

if (!file_exists($certificateOnly)) {
    throw new Exception("Missing cert: ${certificateOnly}");
}

if (!file_exists($privateKey)) {
    throw new Exception("Missing key: ${privateKey}");
}

$data = array(
    array(
        "index" => 1,
        "type" => "URL",
        "data" => $url,
    ),
    array(
        "index" => 100,
        "type" => "HS_ADMIN",
        "data" => array(
            "value" => array(
                "index" => 200,
                "handle" => "0.NA/${prefix}",
                "permissions" => "011111110011",
                "format" => "admin"
            ),
            "format" => "admin",
        ),
    )
);

$payload = json_encode($data);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $handleUrl);
curl_setopt($curl, CURLOPT_PORT , $port);
curl_setopt($curl, CURLOPT_VERBOSE, 1);
curl_setopt($curl, CURLOPT_HEADER, 1);
curl_setopt($curl, CURLOPT_SSLCERT, $certificateOnly);
curl_setopt($curl, CURLOPT_SSLKEY, $privateKey);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Authorization: Handle clientCert="true"',
    'Content-Type: application/json',
    'Accept: application/json',
    'Content-length: '.strlen($payload)
]);

$response = curl_exec($curl);

$header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);

if(curl_errno($curl)){
  echo Curl error: " . curl_error($curl);
}

curl_close($curl);

echo $header . PHP_EOL;
echo $body;

Show handle contents using curl

In this example the created handle can be seen as follows:

curl https://epic-pid.storage.surfsara.nl:8003/api/handles/841/0001e2a0-fb8f-11df-9e4d-523bc2e286e2?pretty
{
  "responseCode": 1,
  "handle": "841/0001e2a0-fb8f-11df-9e4d-523bc2e286e2",
  "values": [
    {
      "index": 1,
      "type": "URL",
      "data": {
        "format": "string",
        "value": "https://www.test.com"
      },
      "ttl": 86400,
      "timestamp": "2019-10-31T13:26:30Z"
    },
    {
      "index": 100,
      "type": "HS_ADMIN",
      "data": {
        "format": "admin",
        "value": {
          "handle": "0.NA/841",
          "index": 200,
          "permissions": "011111110011"
        }
      },
      "ttl": 86400,
      "timestamp": "2019-10-31T12:59:40Z"
    }
  ]
}