Overview

The Repository Update API is a RESTful API for creating, updating, and deleting records and collections in a DDS repository.

Definitions and concepts

The Repository Update API uses a REST-RPC hybrid approach to accept requests expressed as HTTP argument/value pairs. Requests may be made using the HTTP GET or POST method, which behave identically and vary only in the length of the request allowed (GET has a limited request length whereas POST is unlimited). Responses are returned in XML or JSON format (XML by default), which varies in structure and content depending on the request as shown below in the examples section of this document.

• 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://nsdl.org/nsdl_dds/services/ddsupdatews1-1.
• Request arguments - the argument=value pairs that make up the request and follow the base URL.
• Repository Update API 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 Repository Update API 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://nsdl.org/nsdl_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

Summary and usage

A collection is a container for storing XML records in the repository. One or more collection must be created before records can be inserted. The PutCollection request may be used to create an empty collection in the repository or update information about an existing collection such as it's title and description. Upon calling PutCollection, if the collection does not exist, a new one with the given name, description, collectionKey, xmlFormat, and additionalMetadata will be created. If the collection already exists with the given collectionKey and xmlFormat, it's name, description, and additionalMetadata will be updated with the new values indicated. An error is returned if an existing collection exists with a different XML format. To change the XML format, delete the collection and created it again with the new format. Once a collection has been created, records may be inserted into it using the PutRecord request.

Sample request

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

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

Arguments

• collectionKey - a required argument that specifies the key for the collection, for example collection-123. This key must be unique and must contain letters, numbers and the characters period, dash and underscore only ([a-zA-Z0-9.-_]). This value is assigned to the key and record ID for the collection.
• xmlFormat - a required argument that indicates the format for the records 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. This is written to the fullTitle element of the collection record.
• description - an optional argument that contains a description for the collection. If omitted, name is used as the description.
• additionalMetadata - an optional argument that may contain text or XML. If supplied, the contents are written to the additionalMetadata element of the collection record and are searchable using individual XPath search fields when searching over both the collection records as well as the records in the collections.

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

Summary and usage

The DeleteCollection request may be used to delete a collection from the repository. Upon completion, the collection and all records within it will no longer reside in the repository.

Sample request

The following request deletes the collection favorites from the repository:

http://nsdl.org/nsdl_dds/services/ddsupdatews1-1?verb=DeleteCollection&collectionKey=favorites

Arguments

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

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

Summary and usage

The PutRecord request may be used to add or update a single record in the repository. Records must be placed in an existing collection and should conform to the xmlFormat indicated for that collection. If the record does not exist, a new record with the given content will be created. If the record already exists, it will be replaced with the new content. An error is returned if an existing record with the same ID resides in a different collection or if the XML input is not well formed. The caller must validate the record against it's schema and/or ensure integrity of all input prior to insertion if strict data conformance is desired.

Sample request

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

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

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 record in the response to this request.
• collectionKey - a required argument that specifies the key for the collection in which the record will be inserted, for example collection-123. 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 record 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. The caller must validate all input prior to insertion if strict data conformance is desired.

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

Summary and usage

The DeleteRecord request may be used to delete a record from the repository. Upon completion, the record will no longer reside in the repository.

Sample request

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

http://nsdl.org/nsdl_dds/services/ddsupdatews1-1?verb=DeleteRecord&id=SAMPLE-001

Arguments

• id - a required argument that specifies the id for the record 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 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

 

Authentication, authorization, and security

The Repository Update API does not include a native authentication/authorization model, however it is possible to ensure reasonable security by configuring a DDS repository using the techniques outlined below. Appropriate steps should be taken to secure the repository before enabling the API. This section is meant for administrators who are establishing a repository and assumes prior knowledge of network security, Servlets, Tomcat, the Apache web server, and other components in a typical Tomcat webapp installation.

Configuring for security

1. Restrict access to the API to only localhost and/or hosts on a trusted Local Area Network. This may be done by placing Tomcat's http server ports behind a firewalled host that allows access only from localhost and/or other trusted hosts on a closed network. With this kind of host configuration it is possible to use the Apache web server and modproxy or modjk to allow public access to desired portions of the DDS webapp, such as the Search API, while restricting access to the Repository Update API and/or other portions of the webapp.
2. If the API must be accessed over a Wide Area Network, consider the following options:
   1. Configure the API to allow access from authorized IP addresses only. To do so, enter the IP in the configuration section found in the DDS Collection Manager.
   2. Configure the API to run over SSL to ensure all data is encrypted as it is sent over the Internet. The Apache web server may be used to configure SSL, with modproxy or modjk used to provide access to the API and/or other portions of the webapp. Clients must support SSL in order to communicate with the API configured in this way.
   3. Configure the API to require BASIC authorization for access. The Apache web server may be used to configure BASIC Auth, with modproxy or modjk used to provide access to the API and/or other portions of the webapp. Clients must support BASIC auth in order to communicate with the API configured in this way.

Enabling the Repository Update API

The Repository Update API must be enabled before it can be used for a given DDS installation. To enable the service, use the context parameter enableRepositoryUpdateWebService, found in the DDS web.xml deployment descriptor (see comments therein for details).

 

Configuring features for search

The DDS repository system provides a flexible architecture for configuring the search fields, facets, and relationships that are created for the XML records inserted into the repository. See Configuring Search Fields, Facets, and Relationships for XML Frameworks for information.

 

Last revised: $Date: 2012/09/28 19:48:40 $