CINXE.COM

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /> <title>Handle.Net Registry</title> <link href="style/hnr-style.css" rel="stylesheet" type="text/css" /> <meta name="keywords" content="HANDLE.NET Registry, CNRI, Corporation for National Research Initiatives" /> <meta name="description" content="Handle.Net is a DONA MPA." /> </head> <body> <div id="header"> <div style="height:30px;background:#af2d29"><img src="images3/cnri-corp3.jpg" alt="cnri-corp2" width="1000" height="30" align="middle" /></div> <div style="height:1px;background:#ffffff"></div> <div style="height:120px;background:#af2d29"><img src="images3/Handle.Net3.jpg" alt="Handle.Net2" width="1000" height="120" align="middle" /></div> <div style="height:1px;background:#fffff"></div> </div>  <table width="100%" border="0" cellpadding="0" cellspacing="0" align="center"> <tr> <td height="36" width="30" bgcolor="#688bb5"> </td> <td height="36" bgcolor="#688bb5"> <ul id="sddm"> <li><a href="index.html">HOME</a></li> <li><a href="download_hnr.html">SOFTWARE</a></li> <li><a href="prefix.html">PREFIXES</a></li> <li><a href="payment.html">PAYMENT</a></li> <li><a href="hnr_documentation.html">DOCUMENTATION</a></li> <li><a href="hnr_support.html">SUPPORT</a></li> </ul> <div style="clear:both"></div> </td> </tr> </table>  <div style="height:1px;background:#891c19"></div>   <p style="font-size: 18px; color: #000000">HDL.NET<sup>®</sup> Proxy Server System</p> <div class="dotted"> </div> <p>CNRI runs a proxy server system at https://hdl.handle.net/. This HANDLE.NET Service is a collection of web servers that understand the handle protocol. Many implementations of handles intended to help manage web content embed the handles in URLs on web pages, and for the convenience of their customers, use the proxy server for resolution.</p> <p>CNRI's proxy server uses the HDL.NET proxy servlet code that is available for download <a href="#servlet">here</a>.</p> <div class="dotted"><a name="resolving"> </a></div> <p><b>1. Resolving Handles Using the Proxy Server System</b></p> <p>For any HTTP request that combines the proxy's domain name with a handle, for example </p> <p><span class="codes">https://hdl.handle.net/20.1000/5555</span></p> <p>one of the proxy servers will query 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. If there is no URL value, the proxy will display the handle record.</p> <p>In addition to handle values of type <span class="codes">URL</span>, the proxy server understands values of handle value type <span class="codes">10320/loc</span>. These values contain XML describing multiple redirection endpoints for the handle and conditions under which the proxy should use them. For further documentation see the Technical Manual.</p> <p>The proxy server displays a "Handle Not Found" error page when queried for a handle that it cannot find.</p> <p>The handles <span class="codes">20.1000/5555</span> and <span class="codes">20.1000/5555/</span> 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. </p> <p>To speed resolution, the proxy servers cache handle values, with the TTL typically 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.</p> <div class="dotted"><a name="encoding"> </a></div> <p><b>2. Encoding Handles for Use in URIs</b></p> <p>The Handle System<sup>®</sup> 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 percent-encoded.</p> <p>The "#" is another example. Only if you send the proxy server the handle</p> <p><span class="codes">20.1000/5555#resolve</span></p> <p>encoded as</p> <p><span class="codes">https://hdl.handle.net/20.1000/5555%23resolve</span></p> <p>will the proxy correctly resolve the handle. If it is not encoded, <span class="codes">#resolve</span> will be treated as a fragment and removed by the web browser before it gets to the proxy, which will then attempt to resolve <span class="codes">20.1000/5555</span> instead.</p> <p>The following characters, at least, require percent-encoding:</p> <blockquote> <table border="0" cellspacing="2" cellpadding="1"> <tr> <td width="70" align="center">Character</td> <td width="70" align="center">Encoding</td> </tr> <tr> <td align="center">%</td> <td align="center">%25</td> </tr> <tr> <td align="center">#</td> <td align="center">%23</td> </tr> <tr> <td align="center">SPACE</td> <td align="center">%20</td> </tr> <tr> <td align="center">?</td> <td align="center">%3F</td> </tr> </table> </blockquote> <p>Note also that web browser treatment of "/./" and "/../" can be inconsistent. It is recommended that one of the slashes be percent encoded, e.g., change "/./" to "/.%2F" and "/../" to "/..%2F". </p> <div class="dotted"><a name="query-parameters"> </a></div> <p><b>3. Proxy Server Query Parameters</b></p> <div class="indentA">noredirect</div> <div class="indentB">Do not redirect using URL or 10320/loc values; display handle values instead.</div> <div class="indentA">ignore_aliases</div> <div class="indentB">Ordinarily the proxy will take a handle value of type HS_ALIAS to be a handle that should be resolved instead of the input handle; with this parameter values of type HS_ALIAS are ignored.</div> <div class="indentA">auth</div> <div class="indentB">Authoritative query. The proxy will bypass its cache and resolve the handle at an authoritative server.</div> <div class="indentA">cert</div> <div class="indentB">Certified query. The proxy will require an authenticated response from the handle server. Not generally needed by end users.</div> <div class="indentA">index</div> <div class="indentB">Only resolve the handle value at the specified index. May be repeated to resolve multiple indices.</div> <div class="indentA">type</div> <div class="indentB">Only resolve handle values of the specified type. May be repeated to resolve multiple types.</div> <div class="indentA">urlappend</div> <div class="indentB">The value of this parameter is appended to the end of the URL used for redirection.</div> <div class="indentA">locatt=key:value</div> <div class="indentB">For multiple redirection; specifies a key:value pair to determine the choice of redirection from 10320/loc values.</div> <div class="indentA">action=showurls</div> <div class="indentB">For multiple redirection; returns an XML representation of the possible redirect locations.</div>  <div class="dotted"><a name="rest-api"> </a></div> <p><b><a name="rest-api">4. Proxy Server REST API</a></b></p> <p>The handle proxy REST API allows programmatic access to handle resolution using HTTP.</p> <p><i>Example Request/Response</i></p> <p>A REST API request can be made by performing a standard HTTP GET of</p> <p>/api/handles/<handle></p> <p>The API returns JSON.</p> <p>For example, https://hdl.handle.net/api/handles/4263537/4000 yields the response</p> <div class="indentLeft"> <pre> { "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":{ "format":"string", "value":"https://www.handle.net/index.html" }, "ttl":86400, "timestamp":"2001-11-21T16:21:35Z" }, { "index":2, "type":"EMAIL", "data":{ "format":"string", "value":"hdladmin@cnri.reston.va.us" }, "ttl":86400, "timestamp":"2000-04-10T22:41:46Z" } ] } </pre> </div> <div class="dotted"> </div> <p><i>Response Format</i></p> <p>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. </p> <p>Each value is a JSON object with generally 5 attributes:</p> <ul class="blank"> <li style="padding-bottom: .5em;">"index" : an integer </li> <li style="padding-bottom: .5em;">"type" : a string</li> <li style="padding-bottom: .5em;">"data" : an object, see below</li> <li style="padding-bottom: .5em;">"ttl" : the time-to-live in seconds of the value, an integer (or, in the rare case of an absolute expiration time, that expiration time as an ISO8601-formatted string)</li> <li>"timestamp" : an ISO8601-formatted string</li> </ul> <p>Handle value data is an object with properties "format", a string, and "value".</p> <ul> <li>If "format"="string", "value" is a string, representing the data as a UTF-8 string.</li> <li>If "format"="base64", "value" is a string, with a BASE64 encoding of the data.</li> <li>If "format"="hex", "value" is a string, with a hex encoding of the data.</li> <li>If "format"="admin", "value" is an object, representing an HS_ADMIN value, with properties "handle" (a string), "index" (an integer), and "permissions" (a string, representing the bitmask of permissions).</li> <li>If "format"="vlist", "value" is an list of objects, representing an HS_VLIST value; each object in the list has properties "handle" (a string) and "index" (an integer).</li> <li>If "format"="site", "value" is an object, representing an HS_SITE value. As the structure of this object is complicated and generally of limited technical interest it is currently omitted from this documentation.</li> </ul> <div class="dotted"> </div> <p><i>Response Codes</i></p> <ul> <li>1 : Success. (HTTP 200 OK)</li> <li>2 : Error. Something unexpected went wrong during handle resolution. (HTTP 500 Internal Server Error)</li> <li>100 : Handle Not Found. (HTTP 404 Not Found)</li> <li>200 : Values Not Found. The handle exists but has no values (or no values according to the types and indices specified). (HTTP 200 OK)</li> </ul> <div class="dotted"> </div> <p><i>Query Parameters</i></p> <p>This proxy server system REST API is CORS-compliant, however, JSONP callbacks are also supported using a "callback" query parameter.</p> <p>The presence of the "pretty" query parameter instructs the server to pretty-print the JSON output.</p> <p>The "auth" query parameter instructs the proxy server to bypass its cache and query a primary handle server directly for the newest handle data.</p> <p>The "cert" query parameter instructs the proxy server to request an authenticated response from the source handle server. Not generally needed by end users.</p> <p>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,</p> <p>For example, https://hdl.handle.net/api/handles/4263537/4000?type=URL&type=EMAIL&callback=processResponse yields the response</p> <div class="indentLeft"> <pre> processResponse({ "responseCode":1, "handle":"4263537/4000", "values":[ { "index":1, "type":"URL", "data":{ "format":"string", "value":"https://www.handle.net/index.html" }, "ttl":86400, "timestamp":"2001-11-21T16:21:35Z" }, { "index":2, "type":"EMAIL", "data":{ "format":"string", "value":"hdladmin@cnri.reston.va.us" }, "ttl":86400, "timestamp":"2000-04-10T22:41:46Z" } ] }); </pre> </div> <div class="aligncenter" style="width:1000px;height:0;border-top:1px dotted #af2d29;font-size:0;"><a name="servlet">-</a></div> <p><b><a name="servlet">5.</a> Proxy Servlet (ver. 9.3.1)  Java Version</b></p> <p>The proxy servlet code is for developers who want to set up their own proxy server. This is server software, not a web browser plug-in.</p> <p>It is implemented as a <a href="https://www.oracle.com/java/technologies/servlet-technology.html">Java servlet</a> and typically runs under the Apache Tomcat servlet environment.</p> <p>The HTTP-to-Handle servlet enables handle resolution via a web browser. It accepts HTTP GET requests for handles, resolves those handles, and returns an HTTP redirect to the URL value associated with the handle (or randomly chooses one of the URL values if there is more than one). </p> <div class="aligncenter" style="width:1000px;height:0;border-top:1px dotted #af2d29;font-size:0;">-</div> <p class="indent">This software is being made available under the <a href="https://hdl.handle.net/20.1000/115">CNRI License Agreement for Proxy Servlet (ver. 9.3.0)  Java Version</a>. Please read the license carefully and agree to the terms before downloading the software.</p> <div align="center"> <form method="get" action="hnr-source/hdlproxy-9.3.1-distribution.tar.gz"> <input type="submit" value="Download" /> <div style="height:10px;background:#ffffff"></div> <div style="height:1px;background:#b7b7b7"></div> <div align="center"><p class="bottom">February 2, 2023</p></div>  <div style="height:1px;background:#ffffff"></div> </body> </html>