Overview

The Repository Update Service (DDSUpdateWS) is a REST API for adding metadata and content to a DDS repository, allowing authorized clients to create, update and delete collections and items in the repository. Note that this service is disabled for the DLESE library.

Definitions and concepts

DDSUpdateWS is a Representational State Transfer (REST) style Web service API. Service requests are expressed as HTTP argument/value pairs. These requests must be in either GET or POST format. Responses are returned in XML format by default, which varies in structure and content depending on the request as shown below in the examples section of this document. Responses can also be returned as JSON (JavaScript Object Notation) as an alternate output format to XML.

• Base URL - the base URL used to access the Web service. This is the portion of the request that precedes the request arguments. For example http://www.dlese.org/dds/services/ddsupdatews1-1.
• Request arguments - the argument=value pairs that make up the request and follow the base URL.
• DDSUpdateWS response envelope - the XML container used to return data. This container returns different types of data depending on the request made.

HTTP request format

The format of the request consists of the base URL followed by the ? character followed by one or more argument=value pairs, which are separated by the & character. Each request must contain one verb=request pair, where verb is the literal string 'verb' and request is one of the DDSUpdateWS request strings defined below. All arguments must be encoded using the syntax rules for URIs. This is the same encoding scheme that is described by the OAI-PMH.

The HTTP request format has the following structure:
[base URL]?verb=request[&additional arguments].

For example:

http://www.dlese.org/dds/services/ddsupdatews1-1
		?verb=PutRecord&id=SAMPLE-001&xmlFormat=book&collection=favorites
		&recordXml=<book><title>Book+sample</title></book>

 

Requests and responses

This section describes the available requests, or verbs, and the XML responses returned by the service. Responses can also be output in JSON form.

PutCollection

Sample request

The following request adds or updates the collection favorites, xmlFormat book, assigning it the name My favorite books:

http://www.dlese.org/dds/services/ddsupdatews1-1?verb=PutCollection&collectionKey=favorites&xmlFormat=book&name=My+favorite+books

Summary and usage

The PutCollection request is used to add or update a collection in the repository. If the collection does not exist, a new collection with the given name, description, collectionKey and xmlFormat will be created. If the collection already exists, it's name and description will be updated with the new values indicated. An error is returned if an existing collection already exists with a different XML format. Once a collection has been created items may be inserted into the collection using the PutRecord request.

Arguments

• collectionKey - a required argument that specifies the key for the collection, for example dcc. This key must be unique and must contain letters, numbers and the characters period, dash and underscore only ([a-zA-Z0-9.-_]).
• xmlFormat - a required argument that indicates the format for the items that reside this collection, for example oai_dc. The xml format must contain letters, numbers and the characters period, dash and underscore only ([a-zA-Z0-9.-_]).
• name - a required argument that contains a descriptive name for the collection.
• description - an optional argument that contains a description for the collection.

Examples

See example above.

Response

The service responds with data about the result of the request operation. In addition, see result codes.

Errors and exceptions

If an error occurs, an error response is returned. See error and exception conditions.

DeleteCollection

Sample request

The following request deletes the collection favorites from the repository:

http://www.dlese.org/dds/services/ddsupdatews1-1?verb=DeleteCollection&collectionKey=favorites

Summary and usage

The DeleteCollection request is used delete a collection from the repository. Upon completion, the collection and all items within it will be removed from the repository.

Arguments

• collectionKey - a required argument that specifies the key for the collection to delete, for example dcc.

Examples

See example above.

Response

The service responds with data about the result of the request operation. In addition, see result codes.

Errors and exceptions

If an error occurs, an error response is returned. See error and exception conditions.

PutRecord

Sample request

The following example request adds or updates the metadata record ID SAMPLE-001, xmlFormat book in collection favorites:

http://www.dlese.org/dds/services/ddsupdatews1-1?verb=PutRecord&id=SAMPLE-001&xmlFormat=book&collectionKey=favorites&recordXml=<book><title>Book+sample</title></book>

Summary and usage

The PutRecord request is used to add or update a single item in the repository. Items must be placed in existing collection and should conform to the xml format for that collection. If the item does not exist, a new record with the given content will be created. If the item already exists in the collection it will be replaced by the new content indicated. An error is returned if an existing record with the same ID resides in a different collection or if the XML format indicated does not match that of the collection.

Arguments

• id - a required argument that specifies the identifier for the record. Note that for certain XML formats the identifier is derived from the record XML, in which case this value is ignored. The service returns the identifier it assigns for the item in the response to this request.
• collectionKey - a required argument that specifies the key for the collection in which the item will be inserted, for example dcc. This key corresponds to the one indicated in the PutCollection request.
• xmlFormat - a required argument that indicates the format of the record, which must match the format associated with the collection in which the item is being put, for example oai_dc. This xmlFormat corresponds to the one indicated in the PutCollection request.
• recordXml - a required argument that contains the XML for the record being inserted. The XML should conform to the format specified in the xmlFormat argument.

Examples

See example above.

Response

The service responds with data about the result of the request operation. In addition, see result codes.

Errors and exceptions

If an error occurs, an error response is returned. See error and exception conditions.

DeleteRecord

Sample request

The following request deletes the item SAMPLE-001 from the repository:

http://www.dlese.org/dds/services/ddsupdatews1-1?verb=DeleteRecord&id=SAMPLE-001

Summary and usage

The DeleteRecord request is used delete an item from the repository. Upon completion, the item will be removed from the repository.

Arguments

• id - a required argument that specifies the id for the item to delete.

Examples

See example above.

Response

The service responds with data about the result of the request operation. In addition, see result codes.

Errors and exceptions

If an error occurs, an error response is returned. See error and exception conditions.

 

Result Codes

When the service responds to a request it includes a <result> element and resultCode attribute that indicates the result of the request. Clients are advised to test the value of these codes and respond appropriately. A human readable message is also supplied.

Result Codes	Description	Applicable Verbs
success	The result of the request was successful.	all verbs
collectionDoesNotExist	The collection indicated does not exists in the repository.	DeleteCollection
recordDoesNotExist	The record indicated does not exists in the repository.	DeleteRecord

 

Error and Exception Conditions

If an error or exception occurs, the service returns an <error> element with the type of error indicated by a code attribute. Clients are advised to test the value of these codes and respond appropriately. A human readable error message is also supplied.

Error Codes	Description	Applicable Verbs
badVerb	Value of the verb argument is not a legal or the verb argument is missing.	N/A
badArgument	The request includes illegal arguments, is missing required arguments, includes a repeated argument, or values for arguments have an illegal syntax.	all verbs
serviceDisabled	The service is disabled and not available for the repository.	all verbs
illegalOperation	The operation is not legal for the given request.	all verbs
notAuthorized	The client that made the request is not authorized to use the service.	all verbs
internalServerError	The server encountered a problem and was not able to respond to the request.	all verbs

 

System Administration

This section describes system installation and configuration options for the DDS repository system, meant for system administrators. It assumes familiarity with Servlets, Tomcat, Web servers and other server components.

Authorization and Configuration

A client is authorized by it's IP. Valid IPs are specified in the Collection Manager. In addition, the DDS repository system must have the Service enabled in order for it to be used (it is disabled by default), which is configured using the context parameter enableRepositoryUpdateWebService in Tomcat or other servlet container.

The Service does not natively require user names and passwords or encrypt data. When enabling the Service, it is recommended to configure the server to run over SSL with BASIC Authorization or configure for use by local clients only over a local http port that is firewalled and cannot be accessed from the Internet or outside networks.

The DDS repository system provides a flexible architecture for configuring the search fields that are created for the XML items inserted into the repository. See Configuring Search Fields for XML Frameworks for information.

 

Last revised: $Date: 2010/03/09 03:45:49 $