Skip to content

API for developers (Handle rest api 9.0)#

Information on how to use the API

Start using the API#

Authentication#

For creating and modifying handles you need to authenticate at the Handle API service. Authentication using the API is straightforward. There are two main possibilities:

  • Authenticating using username and password
  • Authenticating using client certificates

Authentication using client certificates#

Using client certificates, you need to provide paths to your private key and to the certificate in pem format. In order to explain we are going to use an example via CURL. This can be read as follows:

curl -H "Content-Type:application/json" -H 'Authorization: Handle clientCert="true"' --cert ./certificate_only.pem --key ./privkey.pem

Authentication using username and password#

If you have a username (something that looks like 300:foo/bar) and a password, then the curl request starts as displayed in the example below

curl -H "Content-Type:application/json" -u "301%3AUSERNAME:KEY" …..

CREATE#

Request#

In order to create a new PID you need to make the following request 

curl -H "Content-Type:application/json" -u "301%3AUSERNAME:KEY" -X POST --data <<DATA>> ENDPOINT/YOUR-PID-NAME

Data#

The data that you need to prepare in order to create a PID are as follows. 

'{"values":[
{"index":1,"type":"URL","data":{"format":"string","value":"https://www.eudat.eu"}},
{"index":100,"type":"HS_ADMIN","data":{"format":"admin",
"value":{"handle":"USERNAME","index":200,"permissions":"011111110011"}}}
]}'

Response#

The response is as follows 

{
   "responseCode": 1,
   "handle": "PREFIX/YOUR-PID-NAME"
}

Update#

Request#

When you want to update various values of your PID , then you use at the end of the url ?index=various

curl -H "Content-Type:application/json" -u "301%3AUSERNAME:KEY"  -X PUT --data <<DATA>>  
ENDPOINT/YOUR-PID-NAME?index=various

When you want to update a specific key of your PID , then you use at the end of the url ?index=Number of the key

curl -H "Content-Type:application/json" -u "301%3AUSERNAME:KEY"  -X PUT --data <<DATA>>  
ENDPOINT/YOUR-PID-NAME?index=1

DATA#

When you want to update various values of your PID with ?index=various then the data should have the following format 

{"values": [
   {"index":1,"type":"URL","data":{"format":"string","value":"https://www.eudat.eu/news"}},
   {"index":2,"type":"pagetype","data":{"format":"string","value":"page type is news "}},
   {"index":3,"type":"format","data":{"format":"string","value":"html"}}
]}

When you want to update the value of key 1 of your PID with ?index=1 then the data should have the following format 

{"values": [
   {"index":1,"type":"URL","data":{"format":"string","value":"https://www.eudat.eu/news"}},
]}

Resolve & Get data of a PID#

In order to resolve a PID the only thing you need to know is the endpoint and the name of your PID

Request#

The curl request is as follows 

curl -H "Content-Type:application/json" -X GET  ENDPOINT/YOUR-PID-NAME

Response#

The response is as follows

{
   "responseCode": 1,
   "handle": "PREFIX/YOUR-PID-NAME",
   "values": [
       {
           "index": 1,
           "type": "URL",
           "data": {
               "format": "string",
               "value": "https://www.eudat.eu"
           },
           "ttl": 86400,
           "timestamp": "2023-06-23T10:50:32Z"
       },
       {
           "index": 100,
           "type": "HS_ADMIN",
           "data": {
               "format": "admin",
               "value": {
                   "handle": "USERNAME",
                   "index": 301,
                   "permissions": "011111110011"
               }
           },
           "ttl": 86400,
           "timestamp": "2023-06-23T10:50:32Z"
       }
   ]
}

Delete#

Although you may not be allowed to delete a handle, the delete api action is as in the example below

Request#

The curl request is as follows 

curl -H "Content-Type:application/json" -X DELETE ENDPOINT/YOUR-PID-NAME

Response#

The response is as follows

{
   "responseCode": 1,
   "handle": "PREFIX/YOUR-PID-NAME"
}

API Resources#

The primary resource in this api is the handle record for a handle:

  • {handle} The handle record for handle {handle}.
  • {handle}?index={index} URI query parameters can be used to specify that the resource in question is restricted to one or more of the handle values from the handle record. This is detailed in the method documentation. Another resource is the collection of handles:
  • handles?prefix={prefix} The list of handles available at this server under prefix {prefix}.

Generally supported URI query parameters: - callback={callback} Allows the use of JSONP. The response entity will be wrapped in {callback}(…). - pretty=[true|false] If true responses are pretty-printed. Default false. For any boolean query parameter, the parameter without any value (e.g. ?pretty) is considered to have value true.

API Responses#

The Handle server HTTP interface has in the past responded to requests in the native binary Handle protocol of RFC 3652. As of version 8 requests can also be made using a REST API, with requests and responses expressed via JSON encoding. This API may be useful for server administration or for developing applications using Handle, especially those not developed in Java and thus unable to use the Client SDK. By default the Handle server HTTP interface will respond to requests using HTTP or HTTPS, on the same port. This is called “port unification” and was preferred in order to allow legacy servers to upgrade to v8 and receive the full benefits of the REST API without requiring a new port to be made available. Administrative operations using the REST API require the use of HTTPS. Handle servers generally use self-signed certificates which can not be validated using the typical browser certificate validation.

Response entities#

Response entity: an object with the following properties: - “responseCode”: Handle protocol response code for the message. - “handle”: The handle specified in the request. - “message”: For error responses, an error message. - “values”: An array of handle values

Response statuses#

All response entities are JSON. Response statuses:

  • 200 OK The operation succeeded.
  • 201 Created The operation succeeded and resulted in a new handle or new handle values being created.
  • 400 Bad Request Returned for a incorrectly formatted or otherwise invalid request. Also returned for a request for a handle for which a server is not responsible.
  • 401 Unauthorized The operation requires an authorized caller, but the call in not authenticated.
  • 403 Forbidden The caller is authenticated but not authorized to perform the operation.
  • 404 Not Found The handle in question does not exist.
  • 409 Conflict A request to PUT a handle or handle values specified not to overwrite, but the handle or handle values already exist.
  • 500 Internal Server Error Something unexpected has gone wrong on the server.

Many response entities include a “responseCode” property which is the Handle protocol response code. Some common response codes and the corresponding HTTP status codes are:

  • 1: Success (200 OK or 201 Created) HANDLE.NET (Ver. 9) Technical Manual
  • 2: An unexpected error on the server (500 Internal Server Error)
  • 100: Handle not found (404 Not Found)
  • 101: Handle already exists (409 Conflict)
  • 102: Invalid handle (400 Bad Request)
  • 200: Values not found (in resolution, 200 OK; otherwise 400 Bad Request)
  • 201: Value already exists (409 Conflict)
  • 202: Invalid value (400 Bad Request)
  • 301: Server not responsible for handle (400 Bad Request)
  • 402: Authentication needed (401 Unauthorized)
  • 40x: Other authentication errors (403 Forbidden)

More information can be found here https://hdl.handle.net/20.1000/113 in the technical documentation of Handle.net