REST API Response Format

<< Click to Display Table of Contents >>

Navigation:  Appendix > DOI REST API Request and Response Formats >

REST API Response Format

The REST API response is a JSON object which includes a response code, an echo of the resolved Handle identifier, and either a list of DOI record elements or, in the case of an error, an optional message which is a string describing the error. The figure below shows a response example.

doi_0019_zoom18

hmtoggle_arrow1 Response Code

The response code is an integer referring to a Handle System protocol response code. The most common response code values are:

•1 : Success. (HTTP 200 OK)

•2 : Error. Something unexpected went wrong during DOI name resolution. (HTTP 500 Internal Server Error)

•100 : Handle Not Found. (HTTP 404 Not Found)

•200 : Values Not Found. The Handle Record exists but the required elements do not exist.

hmtoggle_arrow1 Element Data

An element consists of:

•an index (an integer): unique element identifier inside the Handle Record

•a type (a string): for example, URL, description, IP address, email address, etc.

•a value (a data object): see table below

•a timestamp (an ISO8601-formatted string): date and time of the last data update

•a Time To Live (TTL; an integer, or, in the rare case of an absolute expiration time, an ISO8601-formatted string): specifies how long the element value can be cached before the information source should again be consulted

The table below describes the "value" property depending on the "format" property of the element data object. For more information about HS_ADMIN, HS_VLIST and HS_SITE data, see Digital Object Identifier Resolution Protocol (DO-IRP) Specification.

 

"format" property

"value" property

"string"

Is a string representing the data as a UTF-8 string.

"base64"

Is a string, with a BASE64 encoding of the data.

"hex"

Is a string, with a hex encoding of the data.

"admin"

Is an object representing an HS_ADMIN element (Handle administrator) with the properties:

•"handle": identifier of the Handle used to identify the administrator

•"index": index of the element in the administrator's Handle Record storing the administrator's public key

•"permissions": access rights to the Handle Record granted to the administrator

"vlist"

Is an object representing an HS_VLIST element (refers to a list of administrators (public keys in Handle Records)).

"site"

Is an object representing an HS_SITE element (Handle service site information).