|
HDL.NET Services: Proxy Server System
1. Resolving Handles Using the Proxy Server System CNRI runs a proxy server system at http://hdl.handle.net/. This HDL.NET Service is a collection of web servers that understand the handle protocol and know how to talk to the Handle System. Many implementations of the Handle System intended to help manage web content use handles embedded in URLs on web pages, and for the convenience of their customers, use the proxy server for resolution. CNRI's proxy server uses the proxy servlet code that is available for download. The DOI® System is an implementation of the Handle System that uses handles that are called DOI names. The International DOI Foundation runs a proxy server system at http://dx.doi.org. 1. Resolving Handles Using the Proxy Server System For any HTTP request that combines the proxy's domain name with a handle, for example http://hdl.handle.net/4263537/5555 one of the proxy servers will query the Handle System for the handle, take the URL in the handle record (or if there are multiple URLs in the handle record it will select one, and that selection is in no particular order) and send an HTTP redirect to that URL to the user's web browser. The proxy server will return a specific URL if the query includes its unique index value. For example, http://hdl.handle.net/4263537/5555?index=3 will redirect the user's web browser to the URL with index value 3. The proxy server displays a "Handle Not Found" error page when queried for a handle that it cannot find. The handles 4263537/5555 and 4263537/5555/ are both valid handles, but it is unusual for a handle to have trailing slash. If a resolution request for a handle with a trailing slash is received by the proxy server and that handle is not found, the proxy server will return an error report that includes a warning that the requested handle contained a trailing slash, and a link to click to resolve the same string without the slash. 2. Proxy Server Configuration Handles may include values other than URLs. These added values are intended for use by more advanced applications which have the ability to take advantage of multiple pieces of data, e.g., the location of enhanced metadata or related objects. The proxy server, which is assumed to be talking to a plain web browser, ignores these values. The Handle System uses UTF-8, a Unicode implementation, and has no character set constraints. But the proxy server is a web server that sends redirects to web browsers using HTTP syntax, so characters in handles that may not be interpreted correctly by web browsers, for example '?', should be avoided or encoded. A non-ASCII character in a handle should be converted to UTF-8, and each UTF-8 byte that isn't ASCII should be %encoded. The "# " is another example. Only if you send the proxy server the handle 4263537/5555#resolve encoded as http://hdl.handle.net/4263537/5555%23resolve will the proxy correctly resolve the handle. If it is not encoded, #test will be treated as a fragment and removed by the web browser before it gets to the proxy, which will then attempt to resolve 4263537/5555 instead. To speed resolution, the proxy servers cache handle values, with the TTL set to 24 hours. This means that if a handle value is changed, it can take up to 24 hours before the new value is returned. 3. Handle/DOI Proxy Server REST API CNRI has deployed an experimental REST API on the handle proxy server system, http://hdl.handle.net, and the DOI proxy server system, http://dx.doi.org. This API allows programmatic access to handle resolution using HTTP. Example Request/Response A REST API request can be made by performing a standard HTTP GET of http://hdl.handle.net/api/<handle> The API returns JSON. For example, http://hdl.handle.net/api/4263537/4000 yields the response
{
"responseCode":1,
"handle":"4263537/4000",
"values":[
{
"index":100,
"type":"HS_ADMIN",
"data":{
"format":"admin",
"value":{
"handle":"0.NA/4263537",
"index":200,
"permissions":"011111111111"
}
},
"ttl":86400,
"timestamp":"2000-04-10T22:41:46Z"
},
{
"index":1,
"type":"URL",
"data":"http://www.handle.net/index.html",
"ttl":86400,
"timestamp":"2001-11-21T16:21:35Z"
},
{
"index":2,
"type":"EMAIL",
"data":"hdladmin@cnri.reston.va.us",
"ttl":86400,
"timestamp":"2000-04-10T22:41:46Z"
}
]
}
Response Format The response is a JSON object which includes a "responseCode" (an integer referring to a Handle protocol response code), an echo of the "handle" resolved, and either a list of "values" or, in the case of an error, an optional "message" which is a string describing the error. Each value is a JSON object with generally 5 attributes:
Handle value data is either a string or an object with properties "format", a string, and "value".
Response Codes
Query Parameters This proxy server system REST API is CORS-compliant, however, JSONP callbacks are also supported using a "callback" query parameter. The "auth" query parameter instructs the proxy server to bypass its cache and query a primary handle server directly for the newest handle data. The "type" and "index" query parameters allow the resolution response to be restricted to specific types and indexes of interest. Multiple "type" and "index" parameters are allowed and values are returned which match any of the specified types or indexes. For example, For example, http://hdl.handle.net/api/4263537/4000?type=URL&type=EMAIL&callback=processResponse yields the response
processResponse({
"responseCode":1,
"handle":"4263537/4000",
"values":[
{
"index":1,
"type":"URL",
"data":"http://www.handle.net/index.html",
"ttl":86400,
"timestamp":"2001-11-21T16:21:35Z"
},
{
"index":2,
"type":"EMAIL",
"data":"hdladmin@cnri.reston.va.us",
"ttl":86400,
"timestamp":"2000-04-10T22:41:46Z"
}
]
});
|
|
1 April 2013
