This guide explains on how to use the Handle API using Python to perform common tasks.

Always make sure to use the right port! Test prefixes use port 8003 and production prefixes use ports 8000-8007 (your exact port number will be provided by the SURF service desk).


Setup

Sessions

Handles can be created one by one using independent API calls. However, if you need to complete more then one API call in a sitting, we recommend initiating a session first. A session only requires authorisation once, at the beginning of the session, instead of after every API call. Sessions will timeout after 10 minutes of inactivity. 

Always make sure to close a session after all calls have been completed.


Python Packages

There are several Python packages that support the Handle API:

  • B2handle: A Python library for interacting with the Handle system server created specifically for the EUDAT project. It has been replaced with pyHandle.
  • pyHandle: A more generic Python library for interacting with the Handle system server that is under active development and support.

Installing pyHandle

The library can be installed from GitHub by following the instructions. pyHandle also offers extensive documentation and tutorials. 


Alternatively you can use pip to install pyHandle under a user account:

pip3 install --user pyhandle

Installing B2handle

While retired, the library can be installed from GitHub by following the instructions.  B2Handle also offers tutorials and training.

Example python scripts using pyHandle

Initiate your client

​See here.

Create a handle

See here.

Show handle contents

To prevent malicious actors from harming our service, we have a security feature that bans IP addresses that attempt to resolve prefixes that we do not host using our API after 3 attempts. The first ban will only last for 10 minutes but each successive failure will double the ban time.



If you are testing new API calls and scripts, we recommend doing so using our test environment as it is not subject to this security policy (see here for more information). 



If you are attempting to resolve a handle that doesn’t belong to you, we recommend doing so with the global resolver and/or your web browser (see here for an example).



If you are unsure as to what your prefix is, please create a ticket in the service portal and we’d be happy to remind you.

See here.

Modify a handle

See here.

Table of contents