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 Python.

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.

Packages

There are several Python packages that support the Handle API:

  • B2HANDLE library: A library defined specifically for EUDAT. EUDAT is a European project.
  • PyHandle library: A library defined as a successor to the B2HANDLE library. A more generic library.

B2HANDLE Python library with API

It is possible to access the EPIC PID service using the B2HANDLE Python library. The code can be found on GitHub, as well as the B2HANDLE documentation. The library needs to be installed first in order to use it.

An example client is can be found here: epicclient2.py

See the EUDAT training GitHub for more examples.

PyHandle Python library with API

It is possible to access the EPIC PID service using the PyHandle Python library. The code can be found on GitHub, as well as the PyHandle documentation. The library needs to be installed first in order to use it.

Create a handle using Python and PyHandle

A sample script to create a handle when the PyHandle library is installed is as follows:

from pyhandle.handleclient import PyHandleClient
from pyhandle.clientcredentials import PIDClientCredentials
from pyhandle.handleexceptions import *
import uuid
import sys
import json

credentials_file = '<path_to_credentials_file>'
prefix = '<prefix>'
location = 'https://www.test.com'
checksum = None
extratypes = {}

cred = PIDClientCredentials.load_from_JSON(credentials_file)
client = PyHandleClient('rest').instantiate_with_credentials(cred)

handle = client.generate_and_register_handle(prefix, location, checksum, extratypes)

It needs a credential file. An example is as follows:

{
    "client": "rest",
    "handle_server_url": "https://epic-pid.storage.surfsara.nl:8003",
    "prefix": "21.T12996",
    "handleowner": "200:0.NA/21.T12996",
    "private_key": "<your-path>/21.T12996_USER01_310_privkey.pem",
    "certificate_only": "<your-path>/21.T12996_USER01_310_certificate_only.pem",
    "HTTPS_verify": "<your-other-path>/TERENA_SSL_CA_3-chain.pem"
}

See EPIC PID - Known issues for known problems and solutions.