This guide explains on how to use the Handle API from the Windows Command prompt to perform common tasks.

Use the right port

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. 

Close your session

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

Setting up curl for Windows users

While Windows 11's default curl command supports OpenSSL, we advise all users to check the current version of curlinstalled on your Windows machine by opening the command prompt:

  1. Press +S on your keyboard.

  2. Type cmd the search field.

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

If the returned text does not explicitly say that it supports OpenSSL 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.

Go to the bin directory of the unzipped curl folder and verify that it provides OpenSSL support:

curl --version

Examples in Windows using curl

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=<suffix>
SET WEBSITE=<website>

Validate the value of the parameters you set:

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

Go to the directory with the curl version that supports OpenSSL and the execute the following:

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':'%WEBSITE%}},{'index':100,'type':'HS_ADMIN','data':{'format':'admin','value':{'handle':'0.NA/%PREFIX%','index':200,'permissions':'011111110011'}}}]}" %PID_SERVER%/%PREFIX%/%SUFFIX%

Show handle contents

Do not use the API for foreign handles

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.

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

Validate the value of the parameters you set:

ECHO %PREFIX%
ECHO %PORT%
ECHO %PID_SERVER%
ECHO %SUFFIX%

Go to the directory with the curl version that supports OpenSSL and the execute the following:

curl %PID_SERVER%/%PREFIX%/%SUFFIX%?pretty

Modify a handle

Much like creating a new handle, you can modify handles using a similar script. You can modify the reference location of the handle (by modifying the value at index 1) or modify/add metadata values at any other indices (except for 1 and 100). The following script specifically adds the value 'some metadata value' with type ‘SOMETYPE’ at index 2 and 3. Note the addition of the parameter 'index=various' to the URL.


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=<suffix>

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 curl version that supports OpenSSL and the execute the following:

curl -v -k  --key %PRIVKEY% --cert %CERTIFICATE% -H "Content-Type:application/json" -H "Authorization: Handle clientCert=true" -X PUT --data "{'values': [{"index":2,"type":"SOMETYPE","data":{"format":"string","value":"some metadata value"}}, {"index":3,"type":"OTHERTYPE","data":{"format":"string","value":"other metadata value"}}]}" %PID_SERVER%/%PREFIX%/%SUFFIX%?index=various

Table of contents

  • No labels