...

A Lightweight Network Interface (for DSpace)

Revised 8 May 06, Larry Stone

This page describes a simple but comprehensive network interface that was developed as part of the CWSpace project. It was designed to be complete enough for most programmatic uses of the DSpace API, particularly submitting and extracting archived materials as packages or byte streams.

...

...

...

...

...

...

...

...

...

...

...

...

...

The absolute path of the URI for each type of content object
is composed as follows:<table>
Panel

<tr><td>DSpace Site::</td><td> /prefix

<nowiki>/</nowiki>

</td></tr>
<tr><td>Lookup handle::</td><td> /prefix

<nowiki>/lookup/handle/</nowiki>

handle, /prefix

...

sequence`/`handle</td></tr>
<tr><td>Community, Collection, Item (DSpace Objects)::</td><td> /prefix

<nowiki>/dso_</nowiki>

persistent-identifier</td></tr>
<tr><td>Bitstream::</td><td> /prefix

<nowiki>/dso_</nowiki>

persisent-identifier

<nowiki>/bitstream_</nowiki>

pid</td></tr>
<tr><td>Workspace Items list::</td><td> /prefix

<nowiki>/workspace</nowiki>

</td></tr>
<tr><td>Workspace Item::</td><td> /prefix

<nowiki>/workspace/wsi_db_</nowiki>

id</td></tr>
<tr><td>Workflow Items list::</td><td> /prefix

<nowiki>/workflow_own/</nowiki>

, /prefix

<nowiki>/workflow_pool/</nowiki>

</td></tr>
<tr><td>Workflow Item::</td><td> /prefix

<nowiki>/workflow_own/wfi_db_</nowiki>

id</td></tr>
<tr><td>EPerson list::</td><td> /prefix

<nowiki>/eperson/</nowiki>

</td></tr>
<tr><td>EPerson::</td><td> /prefix

<nowiki>/eperson/ep_db_</nowiki>

id</td></tr>

Key:

• Wiki Markup
  \[prefix\] was covered above.

• Wiki Markup
  \[persistent-identifier\] is a specially-encoded version of the DSpace object's persistent identifier (such as a Handle). (See discussion of {{/lookup}} below for details).

• Wiki Markup
  \[handle\] is the Handle or other persistent identifier. It may only be used with the {{lookup}} service.

• Wiki Markup
  \[pid\] in the bitstream URI is a _persistent bitstream identifier_.

• Wiki Markup
  \[id\] is the numeric identifier of row in the database, used to identify e.g. an in-progress Item, such as a workflow or workspace

...

Key:

Prefix was covered above.

Persistent-identifier is a specially-encoded version of the DSpace
object's persistent identifier (such as a Handle). (See discussion
of `/lookup` below for details).

Handle is the Handle or other persistent identifier.
It may only be used with the `"lookup"` service.

Pid in the bitstream URI is a persistent bitstream identifier.
In DSpace 1.2 and 1.3, this is the bitstream sequence number.

...

• item.

About Identifiers

DSpace assigns "persistent identifiers", such as Handles, to all of its
first-class content objects. The LNI's resource URIs do not contain
literal DSpace identifiers, however,
because some identifier formats contain characters (e.g. '/') which
cause problems with existing WebDAV software, _even when properly "escaped"._ To work around this problem and to prevent similar trouble with any new
persistent identifier schemes adopted in the future, the LNI transforms
an identifier by its own proprietary process before putting it into a
resource URI. The exact transformation is not published so it can be
changed without affecting clients.

This is actually no limitation for the typical DSpace WebDAV client,
since the client never has to compose its own resource URI for a DSpace
object.
Typically, the client obtains a resource URI in one of these ways:

1. Starting at a known URI, e.g. the DSpace Site, and navigating from there.
2. The URI is given to the client in the response from another WebDAV operation, such as `PROPFIND` PROPFIND.
3. The client starts with a DSpace persistent identifier (e.g. returned by a search service) , and makes a `"lookup"` URI out of it and does an HTTP GET on that to acquire the actual LNI resource URI of the object.

Note that the transformed identifier in a DAV URI is
NOT necessarily a predictable encoding of the object's identifier;
the client should refrain from trying to create this URI itself based on
an identifier – always use the `lookup` lookup resource for that.
Treat these resource
URIs as opaque objects.

Authorizations and Access to Resources

The LNI applies the same authorization model as the Web user interface,
since it is mostly embedded in the DSpace "business logic" layer (or it
should be). The properties of
Communities and Collections are visible to everyone, since they are,
effectively, metadata. The contents of a Community or Collection are
only visible to principals with `READ` READ access, however. Item properties
and contents are likewise only visible to principals with `READ` READ access.

The DSpace authorization model controls all modifications to resources
representing DSpace objects. For example, you need `WRITE` WRITE access on
an object to change or delete WebDAV properties on its corresponding
resource.

The Workspace and Workflow (in-progress) objects mirror the
access controls of their corresponding DSpace objects.

The EPerson resources are an exception, since EPerson objects are not
exposed so explicitly in the Web UI. The logged-in EPerson can modify some
properties on his/her own EPerson object, and can only read most properties
on the others. Administrators can modify all EPersons.

...

Note that Items, Collections, and Communities are all "DSpace Objects"
referenced by persistent identifiers (such as Handles), so they share
the same URI format. The type of DSpace Object which a resource
represents
is available as a WebDAV property: `"dspace:type"`. Its value is an XML
element in the DSpace namespace, one of:

• `<site<site/>` > – the root of the site.
• `<collection<collection/>` > – Collection object.
• `<community<community/>` > – Community object.
• `<item<item/>` > – Item object.
• `<bitstream<bitstream/>` > – Bitstream object.
• `<eperson<eperson-collection/>` > – Set of all EPersons in the site.
• `<eperson<eperson/>` > – An EPerson.
• `<workspace<workspace/>` > – Set of all your workspace items.
• `<workspace<workspace-item/>` > – Workspace item.
• `<workflow<workflow/>` > – Set of workflow items.
• `<workflow<workflow-item/>` > – Workflow item.

The ` "dso_" ` path elements can be cascaded as you descend a hierarchy.
The server only pays attention to the last element in a path
of DSO's, e.g.

<nowiki>httphttp://uni.edu/dspace/dav/dso_123456789$4/dso_123456789$13</nowiki>123456789$13

is the same as

<nowiki>httphttp://uni.edu/dspace/dav/dso_123456789$13</nowiki>123456789$13

Since a Bitstream must be referenced in the context of an Item, it is
identified by an extra pathname element following the URI of an Item.

The root of the URI hierarchy is a special "Site" collection object
which contains top-level properties, and all top-level communities.

Some example URIs:

<nowiki>
    Site          http://uni.edu/dspace/dav

    Lookup        http://uni.edu/dspace/dav/lookup/handle/1721.1/46
                  http://uni.edu/dspace/dav/lookup/handle/1721.1%2F46
                  http://uni.edu/dspace/dav/lookup/bitstream-handle/13/1721.1%2F46

    Community     http://uni.edu/dspace/dav/dso_1721.1$46

    Collection    http://uni.edu/dspace/dav/dso_1721.1$3549

    Item          http://uni.edu/dspace/dav/dso_1721.1$5543
                  http://uni.edu/dspace/dav/dso_1721.1$3549/dso_1721.1$5543

    Bitstream     http://uni.edu/dspace/dav/dso_1721.1$5543/bitstream_13
    Bitstream     http://uni.edu/dspace/dav/dso_1721.1$5543/bitstream_13.pdf
</nowiki>

HTTP and WebDAV Methods (API)

The LNI repsonds to the following HTTP requests using WebDAV methods.
It also supports a SOAP RPC API, which has the same operations
and semantics as the WebDAV methods.

PROPFIND

`PROPFIND` is a core
WebDAV method, an extension to HTTP.
This description also applies to the
`propfind` call in the SOAP API.
`PROPFIND` gets the WebDAV properties bound to a resource, and optionally
for the resource's descendents as well. It has two man uses:

...

In the `PROPFIND` HTTP request, the URI identifies the resource to
be queried.

The body of the request is an XML

...