...
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.
...
Note |
---|
Do not conflate the WebDAV resource URIs with "URLs" to be used in an interactive Web browser. The LNI's resource URIs are not to be used interactively, and should never be archived or saved for later reference. Most of the URIs (with the notable exception of |
Info | ||
---|---|---|
| ||
Prefix is the initial URL path at which |
...
the LNI service is "mounted" on its Web server. Since the LNI is intended |
...
the same one running other DSpace services (e.g. the Web UI), it |
...
will probably be mounted under a separate initial path to distinguish |
...
its requests from those bound for other servlets. For example, |
...
on a server host |
...
" |
...
, if the LNI is mounted at |
...
|
...
|
...
the complete prefix is |
...
...
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
Code Block |
---|
<nowiki>/</nowiki> |
</td></tr>
<tr><td>Lookup handle::</td><td> /prefix
Code Block |
---|
<nowiki>/lookup/handle/</nowiki> |
handle, /prefix
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="954fe225-5885-4d4f-8f14-f2e298b3af6c"><ac:plain-text-body><![CDATA[ | DSpace Site | /[prefix]/ | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="fe665677-f032-469b-9aa2-15d79565a1ee"><ac:plain-text-body><![CDATA[ | Lookup handle | /[prefix]/lookup/handle/[handle] , /[prefix]/lookup/bitstream-handle/ |
...
sequence`/`handle</td></tr>
<tr><td>Community, Collection, Item (DSpace Objects)::</td><td> /prefix
Code Block |
---|
<nowiki>/dso_</nowiki> |
persistent-identifier</td></tr>
<tr><td>Bitstream::</td><td> /prefix
Code Block |
---|
<nowiki>/dso_</nowiki> |
persisent-identifier
Code Block |
---|
<nowiki>/bitstream_</nowiki> |
pid</td></tr>
<tr><td>Workspace Items list::</td><td> /prefix
Code Block |
---|
<nowiki>/workspace</nowiki> |
</td></tr>
<tr><td>Workspace Item::</td><td> /prefix
Code Block |
---|
<nowiki>/workspace/wsi_db_</nowiki> |
id</td></tr>
<tr><td>Workflow Items list::</td><td> /prefix
Code Block |
---|
<nowiki>/workflow_own/</nowiki> |
, /prefix
Code Block |
---|
<nowiki>/workflow_pool/</nowiki> |
</td></tr>
<tr><td>Workflow Item::</td><td> /prefix
Code Block |
---|
<nowiki>/workflow_own/wfi_db_</nowiki> |
id</td></tr>
<tr><td>EPerson list::</td><td> /prefix
Code Block |
---|
<nowiki>/eperson/</nowiki> |
</td></tr>
<tr><td>EPerson::</td><td> /prefix
Code Block |
---|
<nowiki>/eperson/ep_db_</nowiki> |
id</td></tr>
[sequence]/[handle]_ | ]]></ac:plain-text-body></ac:structured-macro> | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="0cbfec57-bccd-4008-8b92-b71ee9ee7c90"><ac:plain-text-body><![CDATA[ | Community, Collection, Item (DSpace Objects) | /[prefix]/dso_[persistent-identifier] | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="0ad7afd7-3398-4ae4-a3c9-76e55ea7e39c"><ac:plain-text-body><![CDATA[ | Bitstream | /[prefix]/dso_[persistent-identifier]/bitstream_[pid] | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="8e8d8738-a617-412a-9084-6d465d0d86bc"><ac:plain-text-body><![CDATA[ | Workspace Items list | /[prefix]/workspace | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="40cc00aa-5106-4c71-a4a7-b02c3b686427"><ac:plain-text-body><![CDATA[ | Workspace Item | /[prefix]/workspace/wsi_db_[id] | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="96e49baa-5a34-4c51-971c-5d00d683d519"><ac:plain-text-body><![CDATA[ | Workflow Items list | /[prefix]/workflow_own/ , /[prefix]/workflow_pool/ | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="00948a35-d065-4579-a7ad-d8e996a9f558"><ac:plain-text-body><![CDATA[ | Workflow Item | /[prefix]/workflow_own/wfi_db_[id] | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="167d0bb2-198e-474a-99b5-258a028784ca"><ac:plain-text-body><![CDATA[ | EPerson list | /[prefix]/eperson/ | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="1792fe3a-71c8-4779-ab48-625c325ef20e"><ac:plain-text-body><![CDATA[ | EPerson | /[prefix]/eperson/ep_db_[id] | ]]></ac:plain-text-body></ac:structured-macro> |
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:
- Starting at a known URI, e.g. the DSpace Site, and navigating from there.
- The URI is given to the client in the response from another WebDAV operation, such as `PROPFIND`
PROPFIND
. - 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.
Code Block |
---|
<nowiki>httphttp://uni.edu/dspace/dav/dso_123456789$4/dso_123456789$13</nowiki>123456789$13 |
is the same as
Code Block |
---|
<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:
Code Block |
---|
<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
...