Fedora REST API Documentation

The Fedora REST API is a new, experimental feature that exposes a subset of the Fedora Access and Management APIs as a RESTful (Representational State Transfer) Web Service. The REST API may replace the API-A-Lite and API-M-Lite interfaces in future versions of Fedora.

As the Fedora REST API is an experimental interface, it should not be considered stable. In particular, future releases may implement a different subset of the Fedora Access and Management APIs and may employ different URL endpoints or HTTP methods. Finally, the REST API has not undergone security testing, so production repositories are cautioned against enabling the REST API without thorough evaluation.

For examples of how to use the REST API programmatically, please refer to the TestRESTAPI test class.

describeRepository

Not implemented

findObjects

URL Syntax

/objects ? [terms | query] [maxResults] [format] [pid] [label] [state] [ownerId] [cDate] [mDate] [dcmDate] [title] [creator] [subject] [description] [publisher] [contributor] [date] [type] [format] [identifier] [source] [language] [relation] [coverage] [rights]

HTTP Method

GET

Parameters

Name	Description	Default	Options
terms	a phrase represented as a sequence of characters (including the ? and * wildcards) for the search. If this sequence is found in any of the fields for an object, the object is considered a match. Do NOT use this parameter in combination with the "query" parameter
query	a sequence of space-separated conditions. A condition consists of a metadata element name followed directly by an operator, followed directly be a value. Valid element names are (pid, label, state, ownerId, cDate, mDate, dcmDate, title, creator, subject, description, publisher, contributor, date, type, format, identifier, source, language, relation, coverage, rights). Valid operators are: contains (~), equals (=), greater than (>), less than (<), greater than or equals (>=), less than or equals (<=). The contains (~) operator may be used in combination with the ? and * wildcards to query for simple string patterns. Space-separators should be encoded in the URL as %20. Operators must be encoded when used in the URL syntax as follows: the (=) operator must be encoded as %3D, the (>) operator as %3E, the (<) operator as %3C, the (>=) operator as %3E%3D, the (<=) operator as %3C%3D, and the (~) operator as %7E. Values may be any string. If the string contains a space, the value should begin and end with a single quote character ('). If all conditions are met for an object, the object is considered a match. Do NOT use this parameter in combination with the "terms" parameter.
maxResults	the maximum number of results that the server should provide at once. If this is unspecified, the server will default to a small value	25
format	the preferred output format	html	xml, html
pid	if true, the Fedora persistent identifier (PID) element of matching objects will be included in the response	false	true, false
label	if true, the Fedora object label element of matching objects will be included in the response	false	true, false
state	if true, the Fedora object state element of matching objects will be included in the response	false	true, false
ownerId	if true, each matching objects' owner id will be included in the response	false	true, false
cDate	if true, the Fedora create date element of matching objects will be included in the response	false	true, false
mDate	if true, the Fedora modified date of matching objects will be included in the response	false	true, false
dcmDate	if true, the Dublin Core modified date element(s) of matching objects will be included in the response	false	true, false
title	if true, the Dublin Core title element(s) of matching objects will be included in the response	false	true, false
creator	if true, the Dublin Core creator element(s) of matching objects will be included in the response	false	true, false
subject	if true, the Dublin Core subject element(s) of matching objects will be included in the response	false	true, false
description	if true, the Dublin Core description element(s) of matching objects will be included in the response	false	true, false
publisher	if true, the Dublin Core publisher element(s) of matching objects will be included in the response	false	true, false
contributor	if true, the Dublin Core contributor element(s) of matching objects will be included in the response	false	true, false
date	if true, the Dublin Core date element(s) of matching objects will be included in the response	false	true, false
type	if true, the Dublin Core type element(s) of matching objects will be included in the response	false	true, false
format	if true, the Dublin Core format element(s) of matching objects will be included in the response	false	true, false
identifier	if true, the Dublin Core identifier element(s) of matching objects will be included in the response	false	true, false
source	if true, the Dublin Core source element(s) of matching objects will be included in the response	false	true, false
language	if true, the Dublin Core language element(s) of matching objects will be included in the response	false	true, false
relation	if true, the Dublin Core relation element(s) of matching objects will be included in the response	false	true, false
coverage	if true, the Dublin Core coverage element(s) of matching objects will be included in the response	false	true, false
rights	if true, the Dublin Core rights element(s) of matching objects will be included in the response	false	true, false

Examples

/objects?terms=demo&pid=true&subject=true&label=true

/objects?query=title%7Erome%20creator%7Estaples&pid=true&title=true&creator=true

/objects?query=pid%7E*1&maxResults=50&format=xml&pid=true&title=true

getDatastreamDissemination

URL Syntax

/objects/{pid}/datastreams/{dsID} ? [asOfDateTime]

HTTP Method

GET

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
{dsID}	datastream identifier
asOfDateTime	indicates that the result should be relative to the digital object as it existed at the given date and time		yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ

Examples

/objects/demo:29/datastreams/DC

/objects/demo:29/datastreams/DC?asOfDateTime=2008-01-01

getDissemination

Not implemented

getObjectHistory

URL Syntax

/objects/{pid}/versions [.xml] ? [format]

HTTP Method

GET

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
.xml	shortcut for specifying xml format
format	the preferred output format	html	xml, html

Examples

/objects/demo:29/versions

/objects/demo:29/versions.xml

/objects/demo:29/versions?format=xml

getObjectProfile

URL Syntax

/objects/{pid} [.xml] ? [format] [asOfDateTime]

HTTP Method

GET

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
.xml	shortcut for specifying xml format
format	the preferred output format	html	xml, html
asOfDateTime	indicates that the result should be relative to the digital object as it existed on the given date		yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ

Examples

/objects/demo:29

/objects/demo:29.xml

/objects/demo:29?format=xml

/objects/demo:29?asOfDateTime=2008-01-01

listDatastreams

URL Syntax

/objects/{pid}/datastreams [/xml] ? [format] [asOfDateTime]

HTTP Method

GET

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
/xml	shortcut for specifying xml format
format	the preferred output format	html	xml, html
asOfDateTime	indicates that the result should be relative to the digital object as it existed on the given date		yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ

Examples

/objects/demo:35/datastreams

/objects/demo:35/datastreams/xml

/objects/demo:35/datastreams?format=xml&asOfDateTime=2008-01-01T05:15:00Z

listMethods

URL Syntax

/objects/{pid}/methods [.xml] ? [format] [asOfDateTime]

HTTP Method

GET

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
.xml	shortcut for specifying xml format
format	the preferred output format	html	xml, html
asOfDateTime	indicates that the result should be relative to the digital object as it existed on the given date		yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ

Examples

/objects/demo:29/methods

/objects/demo:29/methods.xml

/objects/demo:29/methods?format=xml&asOfDateTime=2008-01-01T05:15:00Z

resumeFindObjects

URL Syntax

/objects ? [sessiontoken] [all findObjects options]

HTTP Method

GET

Parameters

Name	Description	Default	Options
sessionToken	the identifier of the session to which the search results are being returned
all findObjects options	all of the same options are available for resumeFindObjects as for findObjects

Examples

/objects?terms=*&format=xml&pid=true&subject=true&label=true&sessionToken=xyz

addDatastream

URL Syntax

/objects/{pid}/datastreams/{dsID} ? [controlGroup] [dsLocation] [altIDs] [dsLabel] [versionable] [dsState] [formatURI] [checksumType] [checksum] [logMessage]

HTTP Method

POST

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
{dsID}	datastream identifier
controlGroup	one of "X", "M", "R", or "E" (Inline XML, Managed Content, Redirect, or External Referenced)	X	X, M, R, E
dsLocation	location of managed or external datastream content
altIDs	alternate identifiers for the datastream
dsLabel	the label for the datastream
versionable	enable versioning of the datastream	true	true, false
dsState	one of "A", "I", "D" (Active, Inactive, Deleted)	A	A, I, D
formatURI	the format URI of the datastream
checksumType	the algorithm used to compute the checksum	DEFAULT	DEFAULT, DISABLED, MD5, SHA-1, SHA-256, SHA-385, SHA-512, HAVAL, TIGER, WHIRLPOOL
checksum	the value of the checksum represented as a hexadecimal string
logMessage	a message describing the activity being performed
Multipart file	Datastream file (for Managed datastreams)

Examples

POST: /objects/demo:29/datastreams/NEWDS?controlGroup=X&dsLabel=New (with Multipart file)

POST: /objects/demo:29/datastreams/NEWDS?controlGroup=M&dsLocation=http://example:80/newds&dsLabel=New

addRelationship

Not implemented

compareDatastreamChecksum

Not implemented

export

URL Syntax

/objects/{pid}/export ? [format] [context] [encoding]

HTTP Method

GET

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
format	the XML format to export	info:fedora/fedora-system:FOXML-1.1	info:fedora/fedora-system:FOXML-1.1, info:fedora/fedora-system:FOXML-1.0, info:fedora/fedora-system:METSFedoraExt-1.1, info:fedora/fedora-system:ATOM-1.0
context	the export context, which determines how datastream URLs and content are represented	public	public, migrate, archive
encoding	the encoding of which the exported XML	UTF-8

Examples

/objects/demo:29/export

/objects/demo:29/export?context=migrate

getDatastream

Not implemented

getDatastreamHistory

Not implemented

getDatastreams

Not implemented

getNextPID

URL Syntax

/objects/nextPID ? [numPIDs] [namespace] [format]

HTTP Method

POST

Parameters

Name	Description	Default	Options
numPIDs	the number of pids to retrieve	1
namespace	the namespace of the requested pid(s)	the default namespace of the repository
format	the preferred output format	html	xml, html

Examples

POST: /objects/nextPID

POST: /objects/nextPID?numPIDs=5&namespace=test

getObjectXML

URL Syntax

/objects/{pid}/objectXML

HTTP Method

GET

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object

Examples

/objects/demo:29/objectXML

getRelationships

Not implemented

ingest

URL Syntax

/objects/ [{pid} | new] ? [label] [format] [encoding] [namespace] [ownerId] [logMessage]

HTTP Method

POST

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the object to be created
new	indicator that a new PID should be created for this object
label	the label of the new object
format	the XML format of the object to be ingested	info:fedora/fedora-system:FOXML-1.1	info:fedora/fedora-system:FOXML-1.1, info:fedora/fedora-system:FOXML-1.0, info:fedora/fedora-system:METSFedoraExt-1.1, info:fedora/fedora-system:ATOM-1.0
encoding	the encoding of which the exported XML	UTF-8
namespace	the namespace to use to create any necessary PIDs	the default namespace of the repository
ownerId	the id of the user to be listed at the object owner
logMessage	a message describing the activity being performed

Examples

POST: /objects/new

POST: /objects/new?namespace=demo

POST: /objects/test:100?label=Test

modifyDatastream

URL Syntax

/objects/{pid}/datastreams/{dsID} ? [dsLocation] [altIDs] [dsLabel] [versionable] [dsState] [formatURI] [checksumType] [checksum] [logMessage] [force]

HTTP Method

PUT

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
{dsID}	datastream identifier
dsLocation	location of managed or external datastream content
altIDs	alternate identifiers for the datastream
dsLabel	the label for the datastream
versionable	enable versioning of the datastream	true	true, false
dsState	one of "A", "I", "D" (Active, Inactive, Deleted)	A	A, I, D
formatURI	the format URI of the datastream
checksumType	the algorithm used to compute the checksum	DEFAULT	DEFAULT, DISABLED, MD5, SHA-1, SHA-256, SHA-385, SHA-512, HAVAL, TIGER, WHIRLPOOL
checksum	the value of the checksum represented as a hexadecimal string
logMessage	a message describing the activity being performed
force	force the update even if it would break a data contract	false	true, false
Multipart file	File to replace existing datastream (for Managed datastreams)

Examples

PUT: /objects/demo:35/datastreams/HIGH (with Multipart file)

PUT: /objects/demo:35/datastreams/HIGH?dsLocation=http://example:80/highDS?logMessage=Update

modifyObject

URL Syntax

/objects/{pid} ? [label] [ownerId] [state] [logMessage]

HTTP Method

PUT

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
label	the new object label
ownerId	the id of the user to be listed at the object owner
state	the new object state - Active, Inactive, or Deleted	A	A, I, D
logMessage	a message describing the activity being performed

Examples

PUT: /objects/demo:29?label=Updated

PUT: /objects/demo:29?state=D?logMessage=Deleted

purgeDatastream

URL Syntax

/objects/{pid}/datastreams/{dsID} ? [startDT] [endDT] [logMessage] [force]

HTTP Method

DELETE

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
{dsID}	datastream identifier
startDT	the (inclusive) start date-time stamp of the range. If not specified, this is taken to be the lowest possible value, and thus, the entire version history up to the endDT will be purged		yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ
endDT	the (inclusive) ending date-time stamp of the range. If not specified, this is taken to be the greatest possible value, and thus, the entire version history back to the startDT will be purged		yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ
logMessage	a message describing the activity being performed
force	force the update even if it would break a data contract	false	true, false

Examples

DELETE: /objects/demo:35/datastreams/HIGH

purgeObject

URL Syntax

/objects/{pid} ? [logMessage] [force]

HTTP Method

DELETE

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
logMessage	a message describing the activity being performed
force	force the update even if it would break a data contract	false	true, false

Examples

DELETE: /objects/demo:29

purgeRelationship

Not implemented

setDatastreamState

URL Syntax

/objects/{pid}/datastreams/{dsID} ? [dsState]

HTTP Method

PUT

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
{dsID}	datastream identifier
dsState	one of "A", "I", "D" (Active, Inactive, Deleted)	A	A, I, D

Examples

PUT: /objects/demo:35/datastreams/HIGH?dsState=D

setDatastreamVersionable

URL Syntax

/objects/{pid}/datastreams/{dsID} ? [versionable]

HTTP Method

PUT

Parameters

Name	Description	Default	Options
{pid}	persistent identifier of the digital object
{dsID}	datastream identifier
versionable	enable versioning of the datastream	true	true, false

Examples

PUT: /objects/demo:35/datastreams/HIGH?versionable=false