Skip to content

B2HANDLE for developers#

Start using the library#

Examples on how to use the library:

  • Authentication
  • libraries to use
  • instantiate a client
  • manage your handle

With this example you can start using the B2HANDLE library in 5 minutes.

Authentication#

For creating and modifying handles* you need to authenticate at the Handle Server you’d like to write to. Authentication using b2handle is straightforward. There are two possibilities:

  • Authenticating using username and password
  • Authenticating using client certificates

Important Notice

Here we assume that you know your username and password or have your private key file and your certificate file ready. If you need to set these up, please see Authenticate at a Handle Server

Authentication using client certificates#

Using client certificates, you need to provide paths to the file containing your private key and to the certificate in a JSON file. The class PIDClientCredentials provides a method load_from_JSON(). This can be read as follows:

cred = PIDClientCredentials.load_from_JSON('my_credentials.json')
client = EUDATHandleClient.instantiate_with_credentials(cred)

The JSON file should look like this:

{
  "baseuri": "https://my.handle.server",
  "private_key": "my_private_key.pem",
  "certificate_only": "my_certificate.pem"
}

Authentication using username and password#

If you have a username (something that looks like 300:foo/bar) and a password, we recommend using this constructor: instantiate_with_username_and_password():

client = EUDATHandleClient.instantiate_with_username_and_password(
  'https://my.handle.server',
  '300:foo/bar',
  'mypassword123'
)

Alternatively, you can store your username and password in a JSON file, instead of paths to certificate and key::

    { “baseuri”: “https://my.handle.server”, “username”: “300:foo/bar”, “password”: “mypassword123” }

Like above, you can read the JSON like as shown above:

cred = PIDClientCredentials.load_from_JSON('my_credentials.json')
client = EUDATHandleClient.instantiate_with_credentials(cred)

Credentials JSON file#

The JSON file can contain more information. All items it contains are passed to the client constructor as config. Please see init() to find out which configuration items the client constructor understands.

Libraries to import#

At the beginning of your python code just import 

#!/usr/bin/env python

import sys
import b2handle
from b2handle.clientcredentials import PIDClientCredentials
from b2handle.handleclient import EUDATHandleClient
from b2handle.handleexceptions import *
from requests.exceptions import SSLError

Instantiate your client#

The first thing you have to do is to instantiate your client.

But before that you have to create a json file with the necessary data to connect to the handle server. The file uses certificates in order to authenticate with the Handle server.

mycredentials.json

{
  "handle_server_url": "https://myserver.com",
  "private_key": "privkey.pem",
  "certificate_only": "certificate_only.pem",
  "prefix": "21.11111",
  "handleowner": "301:11239/ADMINUSER",
  "HTTPS_verify": "True"
}

Then instantiate your client 

    print "Creating credentials"
    cred = PIDClientCredentials.load_from_JSON('mycredentials.json')
    client = EUDATHandleClient.instantiate_with_credentials(cred)

    print('PID prefix ' + cred.get_prefix())
    print('Server ' + cred.get_server_URL())

Manage your handle#

The Example#

The example we are going to follow is to create is as follows - Create a test handle with the name MYTEST-HANDLE with the URL http://www.example.com/1. - Read the test handle - Update the test handle by updating the URL to http://www.example.com/2 - Delete the handle

The data of the test handle#

In this section we set the data for the test handle. 

    TEST_SUFFIX='MYTEST-HANDLE'
    VALUE_ORIG='http://www.example.com/1'
    VALUE_AFTER='http://www.example.com/2'
    handle = cred.get_prefix() + '/' + TEST_SUFFIX

Now that we have the data lets start managing the handle.

Create a test handle#

The creation of a handle is the first available action which is supported with register_handle. Basic interactions

You may either register a new Handle with a unique random name (random UUID) or with a predefine value.

In this example we are creating a handle with the name TEST_SUFFIX=’MYTEST-HANDLE’

    # Create test
    print "Creating handle " + handle
    create_result = client.register_handle(handle, VALUE_ORIG)

    if create_result == handle:
        print "OK: Create handle successful."
    else:
        print "PROBLEM: Create handle returned unexpected response."

Read test handle#

With the get_value_from_handle you may retrieve a single value from a single Handle. If several entries with this key exist, the methods returns the first one. If the handle does not exist, the method will raise an exception .Basic interactions

In this example we are reading the predefined handle with key=URL. 

    # Read test
    key = 'URL'
    read_value = client.get_value_from_handle(handle, key)

    if read_value == VALUE_ORIG:
        print "OK: Read handle successful."
    else:
        print "PROBLEM: Read handle returned unexpected response."

Modify test handle#

The library supports the modification of a value in the handle. Basic interactions

With modify_handle_value() a user can modify any number of values in a specific Handle record.

In this example we are going to update the URL of the handle record with the value VALUE_AFTER

    # Modify test
    key = 'URL'
    client.modify_handle_value(handle, **{key: VALUE_AFTER} )
    get_value_result = client.get_value_from_handle(handle, key)

    if get_value_result == VALUE_AFTER:
        print "OK: Modify handle successful."
    else:
        print "CRITICAL: Modify handle value returned unexpected value."
        print "Expected : " + VALUE_AFTER
        print "Returned : " + get_value_result

Delete test handle#

The library supports the Deletion of the handle and its handle record with the delete_function. Basic interactions

In this example we are going to delete the handle we previously created.

    # Delete test
    delete_result = client.delete_handle(handle)
    print "OK: Delete handle successfully."

Last update: 09.11.2023