|
Dienst Protocol Specification
|
Introduction
Dienst
architecture overview
Protocol
Features
Verbs
and Versions
HTTP
embedding of Dienst requests
Dates
Protocol
Messages
Repository
Service
Document
Model
Dissemination
Variables
Partitions
Repository
Verbs
Describe-Verb
Disseminate
Formats
List-Authorities
List-Binders
List-Contents
List-Encodings
List-Meta-Formats
List-Partitions
List-Verbs
List-Versions
New-Version
Submit
Submit-Formats
Structure
Terms
Withdraw
Index
Service
Describe-Verb
Header-Tags
List-Verbs
SearchBoolean
Query Mediator Service
Describe-Verb
List-Verbs
SearchBoolean
Collection Service
Describe-Verb
List-Verbs
Regions
Collection
Publishers
QueryMediators
Indices
Repositories
Info
Service
Describe-Verb
List-Verbs
Identity
List-Services
This document describes the Dienst protocol, which provides for communications with services in a distributed digital library. The word "Dienst" is used in this document and others to refer to a number of things:
The Dienst system (in all three senses) is the foundation for NCSTRL, the Networked Computer Science Technical Report Library.
This document describes the current version of the Dienst protocol. An earlier version of the Dienst protocol, with verbs and features that are still supported by some software implementations (servers), is implemented in another document.
The Dienst architecture is built on the notion of individually defined services that when combined together create a distributed digital library. The word distributed is used since the services and the resources in a Dienst digital library may be located anywhere on the Internet. The functionality of a Dienst digital library includes storage and access to resources (digital objects), deposit of new resources, discovery and browsing of those resources, and user registration.
Communication with and among individual Dienst services takes place via an open protocol, which makes it possible to combine the services in innovative ways, or build other service layers on top of the existing basic Dienst services.
The services defined in the protocol are as follows:
Human interaction with these services and their protocols is mediated by a user interface service.
Individual Dienst protocol requests are called Verbs. Each service supports a set of verbs.
A service may support more than one version of a verb, with each version differing in syntax or semantics. A version takes the form of two integers, separated by a period. This version applies to the individual verb, not the protocol as a whole. (The protocol as a whole does not have a version number. The date on the protocol document indicates the set of verbs that are defined as of that date.) Including a version number in the message allows for backward-compatible extension to the Dienst system.
A server offering one or more Dienst services might support verbs in various versions. A service receiving a message with an older version number must either reply using the old syntax and semantics, or reply with an error. If a service receives a message with a newer version number, then it must return an error.
Software supporting the Dienst protocol may or may not be versioned. If a software version number exists, that number is independent of the Dienst protocol verbs and versions of those verbs that the software supports. Information on the services, verbs, and versions of those verbs supported by an individual server is available through Info service requests.
Dienst protocol requests are expressed as URLs embedded in HTTP requests. Except where as noted, these are all HTTP GET requests. A typical implementation uses a standard Web server, such as Apache, that is configured to dispatch Dienst URLs to the appropriate Dienst service. The remainder of this section describes the aspects of the protocol that are specific to the HTTP embedding.
All messages are encoded into URLs where the path portion of the URL consists of the following tokens, in the following order:
The separator between tokens in the path is the slash, except that the separator before the Keyword Arguments is a question mark.
If the Repository service implemented the Shred verb, and if version 1.2 of that verb accepted two optional keyword arguments (delay and amperage), then an example request is:
/Dienst/Repository/1.2/Shred?delay=9&erage=7.4.
The full URL for this request at a particular Web server might be:
http://bar.com/Dienst/Repository/1.2/Shred?delay=9&erage=7.4.
The syntax rules for URIs restrict a few characters to special roles in certain contexts and require that if these characters are used in any other way that they be written as an escape sequence; a percent sign followed by the character code in hexadecimal. The reserved characters are.
| Character | Role | Escape Sequence |
|
/ |
Path Component Separator |
%2F |
|
? |
Query Component Separator |
%3F |
|
# |
Fragment Identifier |
%23 |
|
= |
Name/Value Separator |
%3D |
|
& |
Argument Separator in Query Component |
%26 |
| : | Host Port Separator | %3A |
| ; | Authority Namespace Separator | %3B |
Finally, the space character may not appear anyplace in a URL. It must be written with a "+" (or with the percent sign escape sequence %20.)
As a result, use of these characters within a Dienst protocol request must be escaped if their use does not correspond to their established URI role. Note that in the examples used throughout this document, special character escaping is shown.
Responses to messages are formatted as HTTP responses, with appropriate HTTP header fields. The return type specified for each message in this document will, therefore, be the MIME type included in the HTTP Content-Type header field (If a wrapper is applied to the content, the Content-Type will correspond to the type of the wrapper). Likewise, any encoding applied to the content will be included in the HTTP Content-Encoding header field.
The responses to Dienst protocol requests vary among the following MIME types:
Status codes and error returns correspond to that defined for HTTP (refer to that protocol documentation). A normal response from a Dienst message in HTTP is signaled with the 200 reply code. Error returns are signaled with the appropriate 4xx or 5xx code as specified in the HTTP protocol. The use of HTTP error codes is as follows:
For each error return, the HTTP reason-phrase returned with the code should provide additional useful information to a human reader.
All dates in the protocol (requests and responses are encoded using the "Complete date" variant of ISO8601. This format is CCYY-MM-DD where CC is the century, YY is the year, MM is the month of the year between 01 (January) and 12 (December), and DD is the day of the month between 01 and 28 or 29 or 30 or 31, depending on length of month and whether it is a leap year.
This section lists the messages (verbs) implemented by each service. Each message has a Name (which is used for purposes of discussion), a Verb (a unique name for the message, used in the protocol to name the message), a Version, a list of Fixed arguments, a list of Keyword Arguments, and a Return MIME type. The documentation for every message includes an example request and response (where appropriate) and the meaning of HTTP error codes that may be returned. These examples uniformly use the handle handlecorp/f970101.
To make reading of this document easier, the DTDs of responses to verbs that return text/xml are separated from the main body of the document into an appendix.
A repository is administratively divided into a set of partitions. Each partition stores documents, as defined by the Dienst document model, and provides messages to deposit documents, discover their structure, and obtain disseminations of documents. A number of dissemination variables effect the nature of a particular dissemination request.
The documents that are stored and delivered in Dienst have a unique identifier (a Handle), and may have multiple versions, logical structure, and multiple content-types. These document model features are expressed in the protocol:
This section describes these features of the document model.
A document is named by a handle, which is a kind of URN. Unlike a URL, a handle is location independent.
A handle has two parts, a naming authority and a string. A naming authority is an entity that is authorized to create new handles and store them in the handle system. Naming authorities are hierarchically organized, with periods used as the separator. For example, handlecorp, handlecorp.research, handlecorp.sales, and handlecorp.sales.hardware. A handle is written with these two parts separated by a slash, for example handlecorp.research/doc1. The character set for handles used in Dienst is restricted to alphanumeric characters, underscore, period, and hyphen (except for the slash separator). (Note that this restriction is specific to Dienst handles and not handles in general). Case is not significant in handles.
A document may have multiple versions. Versions are linear and numbered. The first version is version 1, subsequent versions are 2, 3, etc. A specific version of a document is called a document instance.
Every document instance has a logical structure. The components of this structure are described in the following sections. Refer to the documentation for the Structure verb for the syntax for requesting the structure of a document instance, and the documentation for the Disseminate verb for the syntax for requesting disseminations based on that structure.
Descriptive metadata provides structured (cataloging) information about the document instance or its sub-parts. Typically this cataloging information is used by index services or other discovery or browsing services that facilitate location of digital objects in a digital library. The only restriction on metadata used in Dienst is that it is transported (formatted) in XML. Examples in this document use three metadata standards:
All document instances include descriptive metadata at the top level (for the document instance itself). Optionally, a document instance may also include metadata for individual views and divs, which are described below.
Every document instance has zero or more views. Each view is an alternative expression or structural representation of the content encapsulated in the digital object. Two examples illustrate the notion of alternate views:
Views are strictly alternates. That is, views are not nested and there is no implied ordering in significance or importance among views. Each view within a document instance is uniquely named using an alphanumeric string.
Each view may have descriptive metadata.
Each view may then be hierarchically structured using nested divs. Two examples illustrate the purpose of a div hierarchy:
Each div within a view of a document instance is uniquely named using an alphanumeric string.
Each div may have descriptive metadata.
Each div may then contain one or more terminal elements that are individually disseminable components of the document instance. At present Dienst only supports a single terminal:
Future versions of the protocol may support other terminal elements such as frames in a movie or samples in a digital audio format.
Each terminal within a view of a document instance is uniquely named using an alphanumeric string.
Three dissemination variables affect the actual byte stream that is returned from a Dissemination request. These variables are described in this section.
Every disseminable component of a document (the disseminable components of a document are defined by meta-formats, views, divs, and terminals returned by a Structure request to the document) is available in at least one content type. A content type is a MIME type such as image/tiff or text/html. If no Binder is specified for the dissemination, then the specified Content-type will be the MIME type in the Content-Type header field in the HTTP response to the Dienst protocol request.
For some Dissemination requests, some choices of content type imply a set of logical objects rather than a single object, e.g. requesting five pages of a document as TIFF images, a set of scanned pages of MIME type image/tiff. A binder is used to encapsulate these multiple logical objects. The protocol defines the following set of binders:
Not all binders are supported by all servers. The specification of a Binder changes the MIME type of the Dienst protocol response, which is then reflected in the HTTP Content-Type header field. The list of Binders supported by a repository is available through the List-Binders protocol request.
An encoding is a compression scheme to reduce transmission time. The protocol defines the following set of encodings:
The specification of an Encoding is then reflected in the HTTP Content-Encoding header in the HTTP response to the Dienst protocol request. The list of Encodings supported by a repository is available through the List-Encodings protocol request.
The Repository Service defines the notion of a partition. A partition is an administrator-defined subset of the repository. Each partition has a one token name and a (possibly) longer description. Depending on the policy of a repository an individual document may exist in one or more partitions (the determination of the partition in which a document is located is made in the Submit request). Note that there is, in general, no way to predict in which partition a document appears from its handle, or even given full knowledge of the document.
A repository may have one or more partition hierarchies. For example, an administrator may decide to partition a repository into two hierarchies, one based on institutional affiliation and one based on subjects as follows:
The partition hierarchies in a repository are available via the List-Partitions request.
The Submit and List-Contents verbs include, as an argument, a partition specification. Partition specifications are expressed in the following grammar, where partitionname is the short one token name for the partition:
partitionspec := partitionlist partitionlist := partitionsel | partitionsel;partitionlist partitionsel := partitionname partitionname := [A-Za-z0-9-_]+
Example:
Florida;Frenetics
Where Florida is the short name for Valley View University of Florida and Frenetics is the short name for Department of Frenetics.
Verb: Describe-Verb
Version:
2.0
Fixed args: verb
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response that contains a list, where each element of the list provides information on a version of the specified verb that is supported by this service. The following information may be provided at the verb or version level.
Each element of the list contains the following information:
Note that a service may implement more than one version of a verb.
Example Request:
/Dienst/Repository/2.0/Describe-Verb/Formats
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Describe-Verb version="2.0">
<Verb name="Formats">
<description>Returns a structured response indicating
the formats of disseminations available for this document
</description>
<versions>
<version id="4.0">
<example>http://cs-tr.cs.cornell.edu:80/Dienst/Repository/4.0/Formats/<handle></example>
<arguments>
<fixed>
<arg name="handle" />
</fixed>
<keyword>
<arg name="version" />
<arg name="view" />
</keyword>
</arguments>
</version>
<version id="2.0">
<note>Depricated</note>
<example>http://cs-tr.cs.cornell.edu:80/Dienst/Repository/2.0/Formats/<handle></example>
<arguments>
<fixed>
<arg name="handle" />
</fixed>
</arguments>
</version>
</versions>
</Verb>
</Describe-Verb>
Verb: Disseminate
Version: 1.0
Fixed
args:
handle, view, content-type
Keyword Args: version, <div>,
pageimage, binder,
encoding
Return MIME type: dependent on dissemination requested.
Return Status Codes: 200, 400, 404,
415, 501, 503
Request a dissemination of a digital object. The characteristics of the dissemination that can be requested (the arguments to the Disseminate verb), are determined by the responses to the List-Versions, Formats, and Structure verbs for the specific digital object. The response is a MIME-typed byte stream. The MIME type of the byte stream is either the MIME type of the specified content-type or, if a binder is specified, the MIME type of that binder. Refer to the examples below for more information on the stream that is returned.
In addition to the handle, the required fixed arguments are:
The Keyword Arguments are:
Example Request:
Dienst/Repository/1.0/Disseminate/handlecorp/970101/body/postscript
Example Response:
The PostScript rendition (MIME-type postscript) of "body" view of the document.
Example Request:
Dienst/Repository/1.0/Disseminate/handlecorp/970101/%23oams/xml
Example Response:
The Open Archives metadata record for the document instance (in the only available content-type for metadata which is xml).
<?xml version="1.0"
encoding="UTF-8"?>
<Disseminate version="1.0">
<oams:oams xmlns:oams="http://www.openarchives.org/sfc/sfc_oams.htm">
<oams:title>A protocol for Interoperable
Archives</oams:title>
<oams:accession date="1994-06-24 />
<oams:fullId>ncstrl.cornell/TR94-1418</oams:fullId>
<oams:author>
<oams:name>James R.
Davis</oams:name>
<oams:organization>Xerox</oams:organization>
</oams:author>
<oams:author>
<oams:name>Carl
Lagoze</oams:name>
<oams:organization>Cornell</oams:organization>
</oams:author>
</oams:oams>
</Disseminate>
Example Request:
Dienst/Repository/1.0/Disseminate/handlecorp/970101/book/gif?pageimage=3
Example Response:
Page 3 of the book view of the document instance as a GIF file (MIME type image/gif).
Example Request:
Dienst/Repository/1.0/Disseminate/handlecorp/970101/book/gif
?chapter=3&binder=tar&encoding=gzip
Example Response:
Chapter of the book view of the document instance as a series of GIF files, bound together using tar, and then compressed using gzip. The MIME type of the disseminated byte stream is than application/tar.
Verb: Formats
Version:
4.0
Fixed
args: handle
Keyword Args: version,
view
Return MIME type: text/xml
Return Status Codes: 200,
400, 404, 501
Returns a structured response indicating the formats of disseminations available for this document instance.
The available arguments are:
The response includes the following information:
Example Request:
/Dienst/Repository/4.0/Formats/handlecorp/970101?version=1&part=body
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Formats version="4.0">
<formats>
<postscript name="application/postscript"
size="25555"
URL="http://foo.com/bar.ps" />
<gif name="image/gif" />
</formats>
</Formats>
Verb: List-Authorities
Version:
1.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Return a structured list of the authorities stored in this repository.
Example Request:
/Dienst/Repository/1.0/List-Authorities
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Authorities version="1.0">
<authority>
<name>ncstrl.cornell</name>
<display>Cornell University Computer Science Department</display>
</authority>
</List-Authorities>
Verb: List-Binders
Version:
1.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Return a structured list of the types of binders available in this repository.
Example Request:
/Dienst/Repository/1.0/List-Binders
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Binders version="1.0">
<binder>tar</binder>
</List-Binders>
Verb: List-Contents
Version:
4.0
Fixed args: none
Keyword Args: partitionspec, file-after,
file-before, meta-format
Return MIME type: text/xml
Return Status Codes: 200, 400,
501
Return a structured list of the handles for documents stored in this repository service. Without any arguments the list includes all stored documents.
The meaning of the Keyword Arguments is as follows:
Example Request:
List the handles in the high energy (hep) partition within the physics partition.
/Dienst/Repository/4.0/List-Contents?partitionspec=physics;hep
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Contents version="4.0">
<record>
handlecorp/970101
</record>
<record>
handlecorp/970102
</record>
</List-Contents>
Example Request:
List the rfc1807 metadata along with the handles
/Dienst/Repository/4.0/List-Contents?partitionspec=physics;hep&meta-format=rfc1807
Example Response:
Note the empty rfc1807 record for handlecorp/970102 indicating that there is no rfc1807 metadata for this document.
<?xml version="1.0" encoding="UTF-8"?>
<List-Contents version="4.0">
<record>
handlecorp/970101
<rfc1807:rfc1807 xmlns:rfc1807="ftp://nic.merit.edu/document/rfc/rfc1807.txt">
<rfc1807:author>William Shakespeare</rfc1807:author>
<rfc1807:title>Romeo and Juliet</rfc1807:title>
<rfc1807:id>handlecorp//970101</rfc1807:id>
<rfc1807:entry>June 24 1506</rfc1807:entry>
</rfc1807:rfc1807>
</record>
<record>
handlecorp/970102
<rfc1807:rfc1807 xmlns:rfc1807="ftp://nic.merit.edu/document/rfc/rfc1807.txt"> >
</rfc1807:rfc1807>
</record>
</List-Contents>
Verb: List-Encodings
Version:
1.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Return a structured list of the types of encodings available in this repository.
Example Request:
/Dienst/Repository/1.0/List-Encodings
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Encodings version="1.0">
<Encoding>gzip</Encoding>
</List-Encodings>
Verb: List-Meta-Formats
Version: 1.0
Fixed
args:
none
Keyword Args:
none
Return MIME type: text/xml
Return Status Codes: 200, 400,
501
Returns a structured response indicated the metadata formats that are supported by this repository service. Note that the fact that a metadata format is supported does not mean that it is available for all digital objects in that repository. For each metadata format, the following information is returned:
Example Request:
/Dienst/Repository/1.0/List-Meta-Formats
Example Response:
<?xml version="1.0"
encoding="UTF-8"?>
<List-Meta-Formats version="1.0">
<meta-format name="rfc1807"
namespace="ftp://nic.merit.edu/document/rfc/rfc1807.txt"
/>
<meta-format name="dc"
namespace="http://purl.org/dc"
/>
</List-Meta-Formats>
Verb: List-Partitions
Version: 2.0
Fixed
args:
none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400,
501
Return a structured list of the administrator-determined partitions for documents stored in this repository service. The list contains the hierarchy of partitions and sub-partitions. For each partition, both the short name and long description is returned.
Example Request:
/Dienst/Repository/2.0/List-Partitions
Example Response:
The following response indicates a partition hierarchy with two top level partitions - Oceanside and ValleyView - each with partitions hierarchies within them.
<?xml version="1.0" encoding="UTF-8"?>
<List-Partitions version="2.0">
<partition name="Oceanside">
<display>Oceanside University of Nebraska</display>
<partition name="CompEnt">
<display>Department of Computational Entomology</display>
</partition>
<partition name="MetPhen">
<display>Department of Metaphysical Phenomenology</display>
</partition>
</partition>
<partition name="ValleyView">
<display>Valley View University of Florida</display>
<partition name="Fren">
<display>Department of Frenetics</display>
</partition>
<partition name="Hist">
<display>Department of Histrionics</display>
</partition>
</partition>
</List-Partitions>
This example shows the nested partition lay out described earlier.
Verb: List-Verbs
Version:
2.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the name of the verbs defined by this service.
Example Request:
/Dienst/Repository/2.0/List-Verbs
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Verbs version="2.0">
<verb>Disseminate</verb>
<verb>Formats</verb>
<verb>List-Contents</verb>
<verb>List-Verbs</verb>
</List-Verbs>
Verb: List-Versions
Version: 1.0
Fixed
args:
handle
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200,
400, 501
Returns a structured response describing the current versions (document instances) available for the requested handle. The information returned consists of:
Example Request:
/Dienst/Repository/1.0/List-Versions/handlecorp%2f970101
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Versions version="1.0">
<version id="2">
<date>1999-02-01</date>
<comment>this version</comment>
</version>
<version id="1">
<date>1998-02-01</date>
<comment>that version</comment>
</version>
</List-Versions>
Verb: New-Version
Version: 1.0
Fixed
args: handle
Keyword Args: comment
Return MIME type: text/xml
Return Status Codes: 200, 400,
401, 404, 501
Submit a new version of a document with identifier handle that is currently stored in the repository. The version number of the new version is then one greater than the previous most current version (and it becomes the default version for Disseminate and Structure requests are made without version arguments).
Note on Permissions: It is the responsibility of the repository service implementation to provide some level of access control over the versioning process. One common mechanism is for a repository service implementation to only accept New-Version requests from clients with specific DNS client identifiers. In this case the client is left with the responsibility that the party requesting a new version is authorized to do so.
This is transmitted as a HTTP POST request where the input stream is a MIME type multipart/mixed. This input stream has two parts ordered as follows:
The meaning of the arguments is as follows:
If the new version request is successful the structured return contains:
Example Request:
/Dienst/Repository/1.0/New-Version
?description=fixed+wrong+algorithm
In addition an input stream should be supplied with the POST
that includes this request.
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<New-Version version="1.0">
<version id="2">
<date>1999-02-01></date>
<comment>fixed wrong algorithm</comment>
</version>
</New-Version>
Verb: Structure
Version:
2.0
Fixed
args: handle
Keyword Args: version,
view, content-type
Return MIME type: text/xml
Return Status Codes: 200,
400, 404, 415, 501, 503
This verb returns a structured response that describes the decompositions available for a document instance. A client may use the decomposition information as the basis for document requests using the Disseminate verb.
The meaning of the Keyword Arguments is as follows:
The response lists the meta-formats, views, divs, and pageimages as described above.
Example Request:
/Dienst/Repository/2.0/Structure/handlecorp/970101?version=1
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Structure version="2.0">
<meta-formats>
<rfc1807 />
<dc />
</meta-formats>
<view id="book">
<div id="section 1">
<div id="chapter 1">
<pageimage id="1">
<pageimage id="2">
<pageimage id="3">
</div>
</div>
</view>
</Structure>
This response says that the document instance can disseminate two metadata formats at the top level, rfc1807 and dc (Dublin Core). The document instance also has one disseminable view called body. This view is structured into a section and chapter hierarchy, with individually disseminable pages available at the chapter. (Note that additional sections and chapters have been omitted in the example for brevity).
Example Request:
/Dienst/Repository/2.0/Structure/handlecorp/970101
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Structure version="2.0">
<meta-format>
<rfc1807 />
</meta-format>
<view id="body" divs="pageimage" min="1" max="150" />
</Structure>
This is the "shorthand" response for documents with simple structure. The response indicates one metadata type for the document instance, rfc1807, and a single view, body, with a set of sequential pages numbered from 1 to 150 inclusive.
Example Request:
/Dienst/Repository/2.0/Structure/handlecorp/970101?view=body
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Structure version="2.0">
<view id="body" divs="pageimage" min="1" max="150" />
</Structure>
This request, and the associated response, demonstrates the use of the view argument in the request, which specifies that structure information only for the specified view should be returned.
Example Request:
/Dienst/Repository/2.0/Structure/handlecorp/970101?view=%23
This request specifies that only the metadata formats for the document should be returned.
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Structure version="2.0">
<meta-format>
<rfc1807 />
<dc />
</meta-format>
</Structure>
This response says that the document can disseminate two metadata formats rfc1807 and dc (Dublin Core).
Verb: Submit
Version: 1.0
Fixed
args:
Keyword Args: id, partitionspec,
authority
Return MIME type: text/xml
Return Status Codes: 200, 400,
401, 501
Submit a new document to be stored in the repository. This is transmitted as a HTTP POST request where the input stream is a MIME type multipart/mixed. This input stream has two parts ordered as follows:
The meaning of the arguments is as follows:
If the submit request is successful the structured return contains:
Note on Permissions: It is the responsibility of the repository service implementation to provide some level of access control over the submission process. One common mechanism is for a repository service implementation to only accept Submit requests from clients with specific DNS client identifiers.
Example Request:
/Dienst/Repository/1.0/Submit
?id=handlecorp/970101&partitionspec=compsci;ai
In addition an input stream should be supplied with the POST
that includes this request.
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Submit version="1.0">
<handle>handlecorp/970101</handle>
<partition name="compsci">
<display>
Computer Science
</display>
<partition name="ai">
<display>
Artificial Intelligence
</display>
</partition>
<partition>
</Submit>
Verb: Submit-Formats
Version: 1.0
Fixed args:
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200,
400, 501
Return a structured list of the MIME types of content streams that are accepted by this server in the Submit verb.
Example Request:
/Dienst/Repository/1.0/Submit-Formats
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Submit-Formats version="1.0">
<format>application/postscript</format>
<format>application/pdf</format>
</Submit-Formats>
Verb: Terms
Version:
4.0
Fixed args:
handle
Keyword Args:
none
Return MIME type: text/xml
Return Status Codes: 200,
400, 404, 501
Returns a natural language statement of the terms and conditions for use of the object. The intention is not to create a contract, but only to advise a human of the reasonable expectations of the server or author.
Example Request:
/Dienst/Repository/4.0/Terms/handlecorp/970101
Example Response:
<?xml version="1.0"
encoding="UTF-8"?>
<Terms version="4.0">
<text>Copyright 1999 by the Regents of Oceanview
University, Kansas
</text>
</Terms>
Verb: Withdraw
Version:
1.0
Fixed args:
handle
Keyword Args: reason,
delete, nosave
Return MIME type: text/xml
Return Status Codes: 200,
400, 401, 404, 501
Removes a document from a repository. The following arguments are available:
If the withdraw request is successful the structured return contains:
Note on Permissions: It is the responsibility of the repository service implementation to provide some level of access control over the withdraw process. One common mechanism is for a repository service implementation to only accept Withdraw requests from clients with specific DNS client identifiers. In this case the client is left with the responsibility that the party requesting a withdrawal is authorized to do so.
Note on Policy: The purpose of the Withdraw protocol request is not to dictate policy but provide a mechanism for the implementation of a range of policies. It is expected that each repository will have individual policies for document withdrawal. For example, some repositories may not allow withdrawal at all (will always respond with a 401 error). In other cases, a repository may allow withdrawal of content but insist on maintaining access to the bibliographic record.
Example Request:
/Dienst/Repository/1.0/Withdrawhandlecorp/970101?
&reason=I+was+wrong.+The+world+is+not+flat
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Withdraw version="1.0">
<handle>handlecorp/970101</handle>
</Withdraw>
The index service searches a set of descriptions of documents and return handles for those that match. Typically an index service operates by harvesting metadata from one or more Repository services and storing that metadata in an easily searched index.
Verb: Describe-Verb
Version:
2.0
Fixed args: verb
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response that contains a list, where each element of the list provides information on a version of the specified verb that is supported by this service. The following information may be provided at the verb or version level.
Each element of the list contains the following information:
Note that a service may implement more than one version of a verb.
Example Request:
/Dienst/Index/2.0/Describe-Verb/SearchBoolean
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Describe-Verb version="2.0">
<Verb name="SearchBoolean">
<description>Handles search requests for this index server.
</description>
<version id="5.0">
<example>http://cs-tr.cs.cornell.edu:80/Dienst/Index/5.0/SearchBoolean</example>
<arguments>
<keyword>
<arg name="title" />
<arg name="author" />
<arg name="abstract" />
<arg name="keywords" />
<arg name="boolean" />
<arg name="file-after" />
</keyword>
</arguments>
</version>
</Verb>
</Describe-Verb>
Verb: Header-Tags
Version:
1.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Return a structured response that is a list of the information elements that are returned from a SearchBoolean request.
Example Request:
/Dienst/Index/1.0/Header-Tags
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Header-Tags version="1.0">
<tag>handle</tag>
<tag>rank</tag>
<tag>author</tag>
<tag>title</tag>
<tag>date</tag>
</Header-Tags>
Verb: SearchBoolean
Version:
5.0
Fixed args: none
Keyword Args: see below
Return MIME type: text/xml
Return Status Codes: 200, 400
Specifies a search request to the index server. Keyword Arguments are a set of bibliographic fields and values specifying the search criteria. Returns a structured response that is a list of each document that matches the search criteria. Each element of the list has the following contents:
Note that clients should not assume any logical ordering of the records returned.
Two additional arguments are not affected by the boolean, rather it is always considered to be joined with "and" to the Bibliographic Field Arguments.
A token in a field is either an unquoted word or a quoted string. Tokens are matched to bibliographic entries according to the following rules:
Example Requests:
/Dienst/Index/5.0/SearchBoolean?author=davis+or+fox
/Dienst/Index/5.0/SearchBoolean?author=donald&title=robot
/Dienst/Index/5.0/SearchBoolean?
author=donald&title=computer+vision&boolean=or&authority=xxx
Note the use of the special character "+" to indicate spaces between word tokens in the arguments.
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<SearchBoolean version="5.0">
<record>
<handle>handlecorp/1112</handle>
<rank>2857</rank>
<author>Doe, J.</author>
<author>Public, J. Q.</author>
<title>Answering Queries</title>
<date>19941106</date>
</record>
<record>
<handle>handlecorp/1110</handle>
<rank>2859</rank>
<author>Mouse, M.</author>
<author>Disney, W.</author>
<title>Success with Cartoons</title>
<date>19941106</date>
</record>
</SearchBoolean>
Verb: List-Verbs
Version:
2.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the name of the verbs defined by this service.
Example Request:
/Dienst/Index/2.0/List-Verbs
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Verbs version="2.0">
<verb>SearchBoolean</verb>
<verb>List-Verbs</verb>
</List-Verbs>
The query mediator service performs searches over the entire collection.
Verb: Describe-Verb
Version:
2.0
Fixed args: verb
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response that contains a list, where each element of the list provides information on a version of the specified verb that is supported by this service. The following information may be provided at the verb or version level.
Each element of the list contains the following information:
Note that a service may implement more than one version of a verb.
Example Request:
/Dienst/QM/2.0/Describe-Verb/SearchBoolean
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Describe-Verb version="2.0">
<Verb name="SearchBoolean">
<description>Handles search requests for collection.
</description>
<version id="2.0">
<example>http://cs-tr.cs.cornell.edu:80/Dienst/QM/2.0/SearchBoolean</example>
<arguments>
<keyword>
<arg name="title" />
<arg name="author" />
<arg name="abstract" />
<arg name="keywords" />
<arg name="boolean" />
<arg name="file-after" />
</keyword>
</arguments>
</version>
</Verb>
</Describe-Verb>
Verb: List-Verbs
Version:
2.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the name of the verbs defined by this service.
Example Request:
/Dienst/QM/2.0/List-Verbs
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Verbs version="2.0">
<verb>SearchBoolean</verb>
<verb>List-Verbs</verb>
</List-Verbs>
Verb: SearchBoolean
Version:
2.0
Fixed args: none
Keyword Args: see below
Return MIME type: text/xml
Return Status Codes: 200, 400
Specifies a search request over the entire collection. Keyword Arguments are a set of bibliographic fields and values specifying the search criteria. Returns a structured response that contains optional search statistics and a list of documents that matches the search criteria.
Each element of the document list has the following contents:
Note that clients should not assume any logical ordering of the records returned.
The statistics section contains information about which partitions of the collection returned hits along with information about errors that occurred while processing the search request. Collections are currently segmented by institutional publishing authorities. Authorities returning hits are grouped into buckets according to the number of hits returned.
The statistics error section is organized according to the error received from the remote server since most servers generate similar error messages. Authorites with the same error are included under the same error element.
Two additional arguments are not affected by the boolean, rather it is always considered to be joined with "and" to the Bibliographic Field Arguments.
A token in a field is either an unquoted word or a quoted string. Tokens are matched to bibliographic entries according to the following rules:
Example Requests:
/Dienst/QM/2.0/SearchBoolean?author=davis+or+fox
/Dienst/QM/2.0/SearchBoolean?author=donald&title=robot
/Dienst/QM/2.0/SearchBoolean?
author=donald&title=computer+vision&boolean=or&authority=xxx
Note the use of the special character "+" to indicate spaces between word tokens in the arguments.
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<SearchBoolean version="2.0">
<statistics grouping="hits" segmentation="authority" count="2">
<hits count="2" authorities="1">
<authority name="handlecorp">
</hits>
<errors count="1">
<error text="Can't connect to errorcorp:9999" authorities="1">
<authority name="errorcorp" />
</error>
</errors>
</statistics>
<records>
<record>
<handle>handlecorp/1112</handle>
<rank>2857</rank>
<author>Doe, J.</author>
<author>Public, J. Q.</author>
<title>Answering Queries</title>
<date>19941106</date>
</record>
<record>
<handle>handlecorp/1110</handle>
<rank>2859</rank>
<author>Mouse, M.</author>
<author>Disney, W.</author>
<title>Success with Cartoons</title>
<date>19941106</date>
</record>
</records>
</SearchBoolean>
The collection service provides information about the individual components that make up a collection.
Verb: Describe-Verb
Version:
2.0
Fixed args: verb
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response that contains a list, where each element of the list provides information on a version of the specified verb that is supported by this service. The following information may be provided at the verb or version level.
Each element of the list contains the following information:
Note that a service may implement more than one version of a verb.
Example Request:
/Dienst/Collection/2.0/Describe-Verb/Regions
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Describe-Verb version="2.0">
<Verb name="Regions">
<description>List the regions for this collection.
</description>
<version id="1.0">
<example>http://cs-tr.cs.cornell.edu:80/Dienst/Collection/1.0/Regions</example>
</version>
</Verb>
</Describe-Verb>
Verb: List-Verbs
Version:
2.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the name of the verbs defined by this service.
Example Request:
/Dienst/Collection/2.0/List-Verbs
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Verbs version="2.0">
<verb>Regions</verb>
<verb>Publishers</verb>
<verb>QueryMediators</verb>
<verb>Indices</verb>
<verb>Repositories</verb>
</List-Verbs>
Verb: Regions
Version:
1.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing a list of regions.
Example Request:
/Dienst/Collection/1.0/Regions
Example Response:
<?xml version="1.0"
encoding="UTF-8"?>
<Regions version="1.0">
<Region host="region1host.cs.yourinst.edu"
port="9090"
symbol="NA-EAST" name="North
America - Eastern Region" />
<Region host="region2host.cs.yourinst.edu"
port="9898"
symbol="NA-WEST" name="North
America - Western Region" />
</Regions>
Verb: Collection
Version:
3.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing information about the collection server. This request provides information about the verbs supported by the collection service.
Example Request:
/Dienst/Collection/1.0/Collection
Example Response:
<?xml
version="1.0" encoding="UTF-8"?>
<Collection version="1.0">
<CollectionServer host="chost.cs.yourinst.edu"
port="9891" priority="1">
<Verbs>
<Publishers>
<version>1.0</version>
<version>2.0</version>
<version>3.0</version>
</Publishers>
<Repositories>
<version>2.0</version>
<version>3.0</version>
<version>3.0</version>
</Repositories>
</Verbs>
</CollectionServer>
</Collection>
Verb: Publishers
Version:
3.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the list of publishers that are represented in the collection. All documents in the collection are associated with a publisher.
Example Request:
/Dienst/Collection/3.0/Publishers
Example Response:
<?xml version="1.0"
encoding="UTF-8"?>
<Publishers version="3.0">
<publisher pretty="Cornell University Computer
Science
Department" authority="ncstrl.cornell"
publisher="CORNELLCS">
<publisher pretty="CNR - Instituto di Cibernetica (Napoli)"
authority="ercim.cnr.ic"
publisher="ercim.cnr.ic">
</Publshers>
Verb: QueryMediators
Version:
2.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the name of the verbs defined by this service.
Example Request:
/Dienst/Collection/2.0/QueryMediators
Example Response:
<?xml version="1.0"
encoding="UTF-8"?>
<QueryMediators version="2.0">
<QueryMediator host="qmhost.cs.yourinst.edu"
port="80"
priority="1">
<Verbs>
<Describe-Verb><version>2.0</version></Describe-Verb>
<List-Verbs><version>2.0</version><List-Verbs>
<SearchBoolean>
<version>1.0</version><version>2.0</version>
<SearchBoolean>
</Verbs>
</QueryMediator>
</QueryMediators>
Verb: Indices
Version:
4.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the list of indexers that provide search services on a portion of the collection.
Example Request:
/Dienst/Collection/4.0/Indices
Example Response:
<?xml
version="1.0" encoding="UTF-8"?>
<Indices version="4.0">
<Indexer host="ihost.cs.inst.edu"
port="80" priority="1">
<Authorities>
<authority name="ercim.cnr.ic"
/>
<authority name="ncstrl.cornell"
/>
</Authorities>
<Verbs>
<Describe-Verb><version>1.0</version></Describe-Verb>
<List-Verbs><version>1.0</version><List-Verbs>
<SearchBoolean>
<version>2.0</version><version>3.0</version>
<SearchBoolean>
</Verbs>
</Indexer>
</Indices>
Verb: Repositories
Version:
4.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the list of repositories that store documents contained in the collection.
Example Request:
/Dienst/Collection/4.0/Repositories
Example Response:
<?xml version="1.0"
encoding="UTF-8"?>
<Repositories version="4.0">
<Repository host="rhost.cs.inst.edu"
port="80" priority="1">
<Authorities>
<authority name="ercim.cnr.ic"
/>
<authority name="ncstrl.cornell"
/>
</Authorities>
<Verbs>
<Describe-Verb><version>1.0</version>
<version>2.0</version></Describe-Verb>
<List-Verbs><version>1.0</version>
<version>2.0</version><List-Verbs>
<Structure><version>2.0</version><version>4.0</version>
</Structure>
<Disseminate><version>3.0</version>
</Disseminate>
<Formats><version>4.0</version>
</Formats>
<List-Contents><version>2.0</version><version>4.0</version>
</List-Contents>
</Verbs>
<Repository>
</Repositories>
These messages return general information about the server.
Verb: Describe-Verb
Version:
2.0
Fixed args: verb
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response that contains a list, where each element of the list provides information on a version of the specified verb that is supported by this service. The following information may be provided at the verb or version level.
Each element of the list contains the following information:
Note that a service may implement more than one version of a verb.
Example Request:
/Dienst/Info/2.0/Describe-Verb/List-Services
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Describe-Verb version="2.0">
<Verb name="List-Services">
<description>List services available at this site.
</description>
<version id="1.0">
<example>http://cs-tr.cs.cornell.edu:80/Dienst/Info/1.0/List-Services</example>
</version>
</Verb>
</Describe-Verb>
Verb: List-Verbs
Version:
2.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the name of the verbs defined by this service.
Example Request:
/Dienst/Info/2.0/List-Verbs
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Verbs version="2.0">
<verb>Describe-Verb</verb>
<verb>List-Services</verb>
<verb>Identity</verb>
</List-Verbs>
Verb: Identity
Version:
1.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing information about the identity of the Dienst server.
Example Request:
/Dienst/Info/1.0/Identity
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<Identity version="1.0">
<server>This Server</server>
<localhost>foo.bar.com</localhost>
<localport>80</localport>
<maintainer>jane@bar.com</maintainer>
<daylight_savings_time_zone>EDT</daylight_savings_time_zone>
<standard_time_zone>EST</standard_time_zone>
</Identity>
Verb: List-Services
Version:
1.0
Fixed args: none
Keyword Args: none
Return MIME type: text/xml
Return Status Codes: 200, 400
Returns a structured response containing the names of the defined Dienst services that are supported by this server.
Example Request:
/Dienst/Info/1.0/List-Services
Example Response:
<?xml version="1.0" encoding="UTF-8"?>
<List-Services version="1.0">
<service>Repository</service>
<service>Index</service>
</List-Services>
[Fielding et al., 1997] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee, “Hypertext Transfer Protocol—HTTP/1.1. RFC 2068. U.C. Irvine, DEC, MIT/LCS. January, 1997. ftp://ds.internic.net/rfc/rfc2068.txt
[Lasher, Cohen, 1995] R. Lasher, D. Cohen, “A Format for Bibliographic Records, RFC 1807. Stanford, Myricom. June, 1995. ftp://ds.internic.net/rfc/rfc1807.txt
[ISO 8601] Regretably, the ISO standards are not available online.
[Handles] http://www.handle.net/ Corporation for National Research Initiatives.