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:
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.
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%