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 the command prompt of Windows and curl. To be able to use curl on Windows to communicate to a handle server, you should make sure that the curl version that is installed on your machine supports OpenSSL.

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.

Install curl with OpenSSL support

If you have curl installed, to see the current version on your Windows machine, start a new "Windows System" --> "Command Prompt" in Administrator mode. Change the path to the directory where curl is installed (e.g. 'C:\curl\curl-7.68.0-win64-mingw\bin') and type curl --version.

>curl --version

curl 7.55.1 (Windows) libcurl/7.55.1 WinSSL
Release-Date: [unreleased]
Protocols: dict file ftp ftps http https imap imaps pop3 pop3s smtp smtps telnet tftp
Features: AsynchDNS IPv6 Largefile SSPI Kerberos SPNEGO NTLM SSL

As is visible, this version does not support OpenSSL and therefore another version of curl needs to be installed.

Download the latest version of curl that supports OpenSSL from ​here. Save the zip file and unzip it. To see the version, again go to the bin directory of the unzipped curl folder and check the version (in this case version 7.68).

>curl --version

curl 7.68.0 (x86_64-pc-win32) libcurl/7.68.0 OpenSSL/1.1.1d (Schannel) zlib/1.2.11 brotli/1.0.7 WinIDN libssh2/1.9.0 nghttp2/1.40.0
Release-Date: 2020-01-08
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: AsynchDNS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile MultiSSL NTLM SPNEGO SSL SSPI TLS-SRP brotli libz

With curl version 7.68.0 it is possible to update/create handles in Windows.

Single handle creation in Windows using curl

You can use curl as a simple way to test the creation of a handle. Example below shows how you can set the parameters and run the curl command Windows to create a handle:

In the Windows command prompt, first set the parameters:

SET PREFIX=<your prefix>
SET INDEX=<your index>
SET PORT=<port>
SET PID_SERVER=https://epic-pid.storage.surfsara.nl:%PORT%/api/handles
SET MY_PATH=<path_to_your_private_key_and_certificate>
SET PRIVKEY=%MY_PATH%%PREFIX%_USER01_%INDEX%_privkey.pem
SET CERTIFICATE=%MY_PATH%%PREFIX%_USER01_%INDEX%_certificate_only.pem
SET SUFFIX=uuidgen

Validate the value of the parameters you set:

ECHO %PREFIX%
ECHO %PORT%
ECHO %PID_SERVER%
ECHO %MY_PATH%
ECHO %PRIVKEY%
ECHO %CERTIFICATE%
ECHO %SUFFIX%

Go to the directory with the right curl version which supports OpenSSL and the execute the curl command:

cd C:\curl\curl-7.68.0-win64-mingw\bin

curl -v -k  --key %PRIVKEY% --cert %CERTIFICATE% -H "Content-Type:application/json" -H "Authorization: Handle clientCert=true" -X PUT --data "{'values': [{'index':1,'type':'URL','data':{'format':'string','value':'http://www.test.com'}},{'index':100,'type':'HS_ADMIN','data':{'format':'admin','value':{'handle':'0.NA/%PREFIX%','index':200,'permissions':'011111110011'}}}]}" %PID_SERVER%/%PREFIX%/%SUFFIX%