From NSDLWiki

Contents [hide] 1 NDR API Documentation 2 API Basics 2.1 REST 2.2 Encoding 2.3 Request Structure 2.3.1 HTTP GET requests 2.3.2 HTTP POST requests 2.4 Request Parameters 2.4.1 Handles 2.4.2 inputXML 2.5 Response Structure 2.6 XML Namespace and Schema Locations 2.7 Authentication and Authorization

NDR API Documentation

API Basics

The NDR Application Programming Interface (API) defines REST requests to interact with the repository and its objects (see ObjectTypes). The NDR API uses the underlying Fedora software (http://www.fedora.info/) to read and write stored content. The NDR API is implemented in java with Struts (http://struts.apache.org/) in an Apache-Tomcat (http://tomcat.apache.org/) environment.

REST

REST is a software architectural style for simple web-based interfaces that communicate over HTTP and use XML response data. REST is an acronym for REpresentational State Transfer, indicating a stateless client/server protocol in which each request contains all the information necessary to understand the request. For more information on Representational State Transfer, see the wikipedia entry at http://en.wikipedia.org/wiki/REST.

Encoding

See Encoding documentation covering the basics about UTF-8 character encoding, XML entities, and URL encoding.

Request Structure

Requests are HTTP requests to a base URL followed by the method:

http://<base.url>/<method>[/handle][?args]

Where:

• <base.url> is the repository base URL, generally http://ndr.nsdl.org/api
• <method> is the name of the API call
• [/handle] is the handle of an object (may not be appplicable to all API calls)
• [?args] are additional arguments that may be required by the specific API call

HTTP GET requests

Requests that do not add or modify objects to the NDR use the may use GET method of HTTP, and follow the method name with the handle for an object (see ObjectTypes) in the NDR.

examples:

http://ndr.nsdl.org/api/get/2200/NSDL

http://ndr.nsdl.org/api/findResource?url=http://nsdl.org/

HTTP POST requests

Requests that add or modify objects in the NDR must use the POST method, and may require an inputXML parameter that contains properties, datastreams, or relationships. Since URLs cannot be longer than 2083 characters, and inputXML might be longer than that, inputXML cannot be a parameter in the URI string. Some requests that do not modify NDR data may also require an inputXML parameter, in which case they may use the HTTP POST method as well..

For example, a request to add a resource to the NDR would send an HTTP POST request to

http://ndr.nsdl.org/api/addResource

and include an inputXML argument containing information about the resource to be added in the appropriate XML structure.

Note that HTML forms can be configured to perform an HTTP POST request, so such requests could be made through an HTML interface.

Request Parameters

Handles

Every object in the NDR has a handle - an identifier that uniquely identifies the the object. API requests that operate on a specific object (such as an 'modify' call) require the objects handle as part of the request.

inputXML

InputXML is the name of the parameter to be used with an HTTP POST request to add or modify an object in the NDR. InputXML will contain data required to perform the NDR action. This data is in XML; the exact structure of inputXML depends on which request being called. The individual API documentation pages for each request (see APIRequestsByObject and APIRequestsAlphabetical) describe the XML format required for each request.

The basic structure of the input XML is as follows:

<inputXML xmlns="http://ns.nsdl.org/ndr/request_v1.00/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://ns.nsdl.org/ndr/request_v1.00/ http://ns.nsdl.org/schemas/ndr/request_v1.00.xsd" schemaVersion="1.00.000">

<(objectType)>

<properties>

<[command]>

<(ns:property)>propertyValue</(ns:property)>

...

</[command]>

...

</properties>

<data>

<[command]>

<(ns:datastream)>...</(ns:datastream)>

...

<[command]>

...

</data>

<relationships>

<[command]>

<(ns:relationship)>objectHandle</(ns:relationship)>

...

</[command]>

...

</relationships>

</(objectType)>

</inputXML>

where

• (objectType) is the type of object (e.g. Agent, MetadataProvider, etc.)
• [command] is a command or action to be performed on specific object components (add, delete, replace), and there may be multiple commands within the <properties>, <data> or <relationship> elements. In some contexts, the <command> element is optional, hence the square brackets.
• (ns:property) is a qualified property name, and there may be multiple properties within the <[command]> element.
• (ns:datastream) is a qualified datastream name, and there may be multiple datastreams within the <[command]> element.
• (ns:relationship) is a qualified relationship name. The value of a relationship will be the handle of an existing NDR object. There may be multiple relationships within the <[command]> element.

Note that the order of the <properties>, <data>, and <relationships> elements does not matter, and that they may be empty or even absent.

The root element must be <inputXML> in the namespace http://ns.nsdl.org/ndr/request_v1.00/ and must have the following attributes:

• Namespace declaration for inputXML, xmlns="http://ns.nsdl.org/ndr/response_v1.00/"
• Namespace declaration for the XML schema instance namespace, xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
• xsi:schemaLocation indicating the schema location for NDR inputXML, xsi:schemaLocation="http://ns.nsdl.org/ndr/request_v1.00/ http://ns.nsdl.org/schemas/ndr/request_v1.00.xsd"
• schemaVersion with value 1.00.nnn where nnn is a three digit number (meant to correspond to the minor release of the inputXML schema).

Response Structure

NDR API responses are XML documents containing information about NDR objects affected by the request:

<?xml version="1.0" encoding="UTF-8"?>

<NSDLDataRepository schemaVersion="1.00.000" xmlns="http://ns.nsdl.org/ndr/response_v1.00/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://ns.nsdl.org/ndr/response_v1.00/ http://ns.nsdl.org/schemas/ndr/response_v1.00.xsd">

<responseTime>2005-10-26T19:00:11Z</responseTime>

<requestURL>http://ndr.nsdl.org/api/modifyMetadata/nsdl:281559</requestURL>

<resultData>

<handle>2200/200606041205365T</handle>

</resultData>

</NSDLDataRepository>

All responses will have the following structure:

• Root element <NSDLDataRepository> in the namespace http://ns.nsdl.org/ndr/response_v1.00/ will have the following attributes:
  • Namespace declaration for the response, xmlns="http://ns.nsdl.org/ndr/response_v1.00/"
  • Namespace declaration for the XML schema instance namespace, xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
  • xsi:schemaLocation indicating the schema location for NDR API responses, xsi:schemaLocation="http://ns.nsdl.org/ndr/response_v1.00/ http://ns.nsdl.org/schemas/ndr/response_v1.00.xsd"
  • schemaVersion with value 1.00.nnn where nnn is a three digit number

• <responseTime> as first child of the root element
  • a UTCdatetime indicating the time and date that the response was sent, expressed with “Z” UTC designator for GMT timezone.

• <requestURL> as second child of the root element
  • the URL to which the request was sent, either
    • http://[base.url]/[method] or http://[base.url]/[method]/[handle] for GET requests

OR

• • • http://[base.url]/[method]/[handle] for POST requests

Note that the baseURL in the response may be different than what was used in the request, as there may be redirects or proxypasses from one baseURL to another. (will it stay as is, without the scheme, host or port indicated?)

• The third child of the root element is either:
  • <resultData> containing brief information relevant to the successful performance of a request, including an NDR handle for the affected object(s). The individual API documentation pages for each request describe the exact XML format returned for each request.
  • <error> containing a brief description of the problem preventing the request from being performed.

Here is a sample error response:

<?xml version="1.0" encoding="UTF-8"?>

<NSDLDataRepository schemaVersion="1.00.000" xmlns="http://ns.nsdl.org/ndr/response_v1.00/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://ns.nsdl.org/ndr/response_v1.00/ http://ns.nsdl.org/schemas/ndr/response_v1.00.xsd">

<responseTime>2006-04-03T19:59:14Z</responseTime>

<requestURL>http://ndr.nsdl.org/api/describe/2200/666</requestURL>

<error code="object">Repository object error (for describe) : handle not found in repository: 2200/666</error>

</NSDLDataRepository>

Full descriptions of responses for individual requests are linked to from APIRequestsByObject and APIRequestsAlphabetical.

XML Namespace and Schema Locations

Request inputXML parameter:

• namespace (note trailing slash):
  • http://ns.nsdl.org/ndr/request_v1.00/
• schema location:
  • http://ns.nsdl.org/schemas/ndr/request_v1.00.xsd

Responses:

• namespace (note trailing slash):
  • http://ns.nsdl.org/ndr/response_v1.00/
• schema location:
  • http://ns.nsdl.org/schemas/ndr/response_v1.00.xsd

Authentication and Authorization

The NDR uses signed HTTP headers to authenticate requests that modify the NDR state, and the graph structure to determine authorization. For a detailed overview of the specific authentication and authorization protocols, please refer to the NDR technical document, section 3.