Factsheet

DOI^® Proxy Server System User Documentation

1. Resolving DOIs Using the Proxy Server System
2. Encoding DOIs for Use in URIs
3. Proxy Server Query Parameters
4. Proxy Server REST API

Note that this information, and additional information about the DOI Proxy Server System, Resolution and Numbering, can be found in the DOI Handbook.

Users may resolve DOI names that are structured to use the DOI system Proxy Server (https://doi.org (preferred)). The resolution of the DOI name in this case depends on the use of URL syntax: the example DOI name doi:10.10.123/456 would be resolved from the address: "https://doi.org/10.123/456". Any standard browser encountering a DOI name in this form will be able to resolve it. The proxy service (both doi.org and the earlier but no longer preferred dx.doi.org) is accessible over IPv6, and supports DNSSEC. The proxy servers respond to HTTPS (preferred) as well as HTTP requests.

1. Resolving DOIs using the Proxy Server System

The DOI system uses the Handle System^® to manage digital objects (see the DOI Factsheet "DOI System and the Handle System"). At the infrastructure level, DOI names are handles.

The DOI system Proxy Server is basically a web server that knows how to talk to the Handle System, and at this writing, most DOI^® names found on the web are embedded in URLs that use the proxy server for DOI name resolution. For any HTTP request that combines the proxy's domain name with a DOI name, for example

https://doi.org/10.1000/demo_DOI

the proxy will query the Handle System for the DOI name, 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.

Increasing numbers of DOI names include data in addition to the single default URL. This is sometimes referenced as multiple resolution. 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 documents.

In addition to handle values of type URL, the proxy server understands values of handle value type 10320/loc. These values contain XML describing multiple redirection endpoints for the DOI name and conditions under which the proxy should use them. For further documentation see DOI Handbook Section 3.8.4.3, Resolution of Multiple URLs using the 10320/loc Handle Type.

The proxy server is configured to display a "DOI Name Not Found" error page when queried for a DOI name that it cannot find.

The DOI names 10.1000/demo_DOI and 10.1000/demo_DOI/ are both valid DOI names, but it is unlikely that a DOI name will be created with a trailing slash. If a resolution request for a DOI name with a trailing slash is received by the proxy server and that DOI name is not found, the proxy server will return an error report that includes a warning that the requested DOI name contained a trailing slash, and a link to click to resolve the same string without the slash.

The DOI system Proxy Server is really multiple servers running at multiple locations, with the load distributed evenly across all servers. 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.

Note that the IDF also runs a proxy server for the shortDOI™ Service that is not part of this DOI system Proxy Server specification.

2. Encoding DOIs for use in URIs

The Handle System uses UTF-8, a Unicode implementation, and has no character set constraints. But the DOI system Proxy Server is a web server that sends redirects to web browsers using HTTP syntax, so characters in DOI names that may not be interpreted correctly by web browsers, for example '?', should be avoided or encoded. A non-ASCII character in a DOI name 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 DOI system Proxy Server the DOI name

10.1000/res#test

encoded as

https://doi.org/10.1000/res%23test

will the proxy correctly resolve the DOI name. 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 10.1000/res instead.

Tables 1 and 2 summarize the encoding guidelines for DOI. URLs have the most restricted set of characters. Table 1 lists the characters that should always be hex encoded. Table 2 lists additional characters where it is recommended that characters be replaced by hex-encoding. The distinction between the lists is between practical experience with current web browsers and the more formal specification of URL syntax. In the DOI Directory all characters represent themselves.

Table 1: Mandatory Encoding

Character	Encoding
%	(%25)
"	(%22)
#	(%23)
SPACE	(%20)
?	(%3F)

Table 2: Recommended Encoding

Character	Encoding
<	(%3C)
>	(%3E)
{	(%7B)
}	(%7D)
^	(%5E)
[	(%5B)
]	(%5D)
`	(%60)
|	(%7C)
\	(%5C)
+	(%2B)

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".

3. Proxy Server query parameters

4. Proxy Server REST API

The DOI system Proxy Server REST API allows programmatic access to DOI name resolution using HTTP.

Example Request/Response

A REST API request can be made by performing a standard HTTP GET of

/api/handles/<handle>

The API returns JSON.

For example, https://doi.org/api/handles/10.1000/1 yields the response

{
  "responseCode": 1,
  "handle": "10.1000/1",
  "values": [
    {
      "index": 100,
      "type": "HS_ADMIN",
      "data": {
        "format": "admin",
        "value": {
          "handle": "0.NA/10.1000",
          "index": 200,
          "permissions": "011111111111"
        }
      },
      "ttl": 86400,
      "timestamp": "2000-04-13T15:08:57Z"
    },
    {
      "index": 1,
      "type": "URL",
      "data": { "format": "string", "value": "http://www.doi.org/index.html" },
      "ttl": 86400,
      "timestamp": "2004-09-10T19:49:59Z"
    }
  ]
}

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:

• "index" : an integer
• "type" : a string
• "data" : an object, see below
• "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)
• "timestamp" : an ISO8601-formatted string

Handle value data is an object with properties "format", a string, and "value".

• If "format"="string", "value" is a string, representing the data as a UTF-8 string.
• If "format"="base64", "value" is a string, with a BASE64 encoding of the data.
• If "format"="hex", "value" is a string, with a hex encoding of the data.
• 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).
• 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).
• 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.

Response Codes

• 1 : Success. (HTTP 200 OK)
• 2 : Error. Something unexpected went wrong during handle resolution. (HTTP 500 Internal Server Error)
• 100 : Handle Not Found. (HTTP 404 Not Found)
• 200 : Values Not Found. The handle exists but has no values (or no values according to the types and indices specified). (HTTP 200 OK)

Query Parameters

This DOI system Proxy Server REST API is CORS-compliant, however, JSONP callbacks are also supported using a "callback" query parameter.

The presence of the "pretty" query parameter instructs the server to pretty-print the JSON output.

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 "cert" query parameter instructs the proxy server to request an authenticated response from the source handle server. Not generally needed by end users.

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, https://doi.org/api/handles/10.1000/1?type=URL&callback=processResponse yields the response

processResponse({
  "responseCode": 1,
  "handle": "10.1000/1",
  "values": [
    {
      "index": 1,
      "type": "URL",
      "data": { "format": "string", "value": "http://www.doi.org/index.html" },
      "ttl": 86400,
      "timestamp": "2004-09-10T19:49:59Z"
    }
  ]
});

Updated March 21, 2017