Web Exposure of the Fedora Access Service

Web Exposure

The Fedora repository can be accessed using a simple URL syntax. The Fedora API-A-LITE defines REST-style bindings to run the operations of the Fedora Access service using simple HTTP GET requests. (Fedora API-A defines SOAP/RCP style bindings.) This document describes the URL syntax to run all the operations of the Fedora Access service.

For more information on the method definitions, refer to the API descriptions located at http://www.fedora.info/definitions/1/0/api/.

Running Disseminations (API-A-LITE getDissemination)

URL syntax for the getDissemination request:
http://hostname:port/fedora/get/PID/bDefPID/methodName [/dateTime][?parmArray]

This syntax requests a dissemination of the specified object using the specified method of the associated behavior definition object. The result is returned as a MIME-typed stream.

hostname - required hostname of the Fedora server.
port - required port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
get - a required parameter specifying the Fedora servlet path.
PID - required persistent identifier of the digital object.
bDefPID - required persistent identifier of the behavior definition object to which the digital object subscribes.
methodName - required name of the method to be executed.
dateTime - value indicating dissemination of a version of the digital object at the specified point in time. Proper syntax is YYYY-MM-DDTHH:MM:SS.SSSZ where HH is 24-hour clock and SSS is milliseconds.
parmArray - optional array of method parameters consisting of name/value pairs in the form parm1=value1&parm2=value2...


Example:

Get the Dissemination for a data object with a PID of demo:5, an associated 
behavior definition object with a PID of demo:1, and a methodName of
getThumbnail:
          
	http://localhost:8080/fedora/get/demo:5/demo:1/getThumbnail

Getting Datastreams (API-A-LITE getDatastreamDissemination)

URL syntax for the getDatastream request:
http://hostname:port/fedora/get/PID/DSID [/dateTime]

This syntax requests the contents of a datastream.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
get - a required parameter specifying the Fedora servlet path.
PID - a required parameter specifying the persistent identifier of the digital object.
DSID - identifier of the datastream.
dateTime - an optional dateTime parameter indicating dissemination of a version of the digital object at the specified point in time. Proper syntax is YYYY-MM-DDTHH:MM:SS.SSSZ where HH is 24-hour clock and SSS is milliseconds.


Examples:

Get the Dublin Core datastream (with datastream ID of DC) of demo object demo:5:

	http://localhost:8080/fedora/get/demo:5/DC

Get the thumbnail datastream (with datastream ID of DS1) of demo object demo:5:

	http://localhost:8080/fedora/get/demo:5/DS1

Getting an Object Profile (API-A-LITE getObjectProfile)

URL syntax for the getObjectProfile request:
http://hostname:port/fedora/get/PID [/dateTime][?xml=BOOLEAN]

This syntax requests an object profile for the specified digital object. The xml parameter determines the type of output returned. If the parameter is omitted or has a value of "false", a MIME-typed stream consisting of an html table is returned providing a browser-savvy means of viewing the object profile. If the value specified is "true", then a MIME-typed stream consisting of XML is returned.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
get - a required parameter specifying the Fedora servlet path.
PID - a required parameter specifying the persistent identifier of the digital object.
dateTime - an optional dateTime parameter indicating dissemination of a version of the digital object at the specified point in time. Proper syntax is YYYY-MM-DDTHH:MM:SS where HH is 24-hour clock.
xml - an optional parameter indicating the requested output format. A value of "true" indicates a return type of text/xml; the absence of the xml parameter or a value of "false" indicates format is to be text/html.


Examples:

Get the ObjectProfile for a data object with a PID of demo:5 as HTML:

	http://localhost:8080/fedora/get/demo:5

Get the ObjectProfile for a data object with a PID of demo:5 as XML:

	http://localhost:8080/fedora/get/demo:5?xml=true

Getting an Object's Change History (API-A-LITE getObjectHistory)

URL syntax for the getObjectHistory request:
http://hostname:port/fedora/getObjectHistory/PID [?xml=BOOLEAN]

This syntax requests the change history for the specified digital object. The change history provides a list of timestamps that indicate when components (e.g., datastreams, disseminators, etc.) in the digital object were created or modified. These timestamps can be used in a dissemination request to view the object as it existed at a specific point in time. The xml parameter determines the type of output returned. If the parameter is omitted or has a value of "false", a MIME-typed stream consisting of an html table is returned providing a browser-savvy means of viewing the object history. If the value specified is "true", then a MIME-typed stream consisting of XML is returned.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
getObjectHistory - a required parameter specifying the Fedora servlet path.
PID - a required parameter specifying the persistent identifier of the digital object.
xml - an optional parameter indicating the requested output format. A value of "true" indicates a return type of text/xml; the absence of the xml parameter or a value of "false" indicates format is to be text/html.


Examples:

Get the object history of demo object demo:5 and display the results as HTML:

	http://localhost:8080/fedora/getObjectHistory/demo:5

Get the object history of demo object demo:5 and display the results as XML:

	http://localhost:8080/fedora/getObjectHistory/demo:5?xml=true

Listing Datastreams in an Object (API-A-LITE listDatastreams)

URL syntax for the listDatastreams request:
http://hostname:port/fedora/listDatastreams/PID [/dateTime][?xml=BOOLEAN]

This syntax requests a list of datastreams contained in the digital object.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
listDatastreams - a required parameter specifying the Fedora servlet path.
PID - a required parameter specifying the persistent identifier of the digital object.
dateTime - an optional dateTime parameter indicating dissemination of a version of the digital object at the specified point in time. Proper syntax is YYYY-MM-DDTHH:MM:SS where HH is 24-hour clock.
xml - an optional parameter indicating the requested output format. A value of "true" indicates a return type of text/xml; the absence of the xml parameter or a value of "false" indicates format is to be text/html.


Examples:

List the datastreams in a data object with PID of demo:5 as HTML:

	http://localhost:8080/fedora/listDatastreams/demo:5

List the datastreams in a data object with PID of demo:5 as XML:

	http://localhost:8080/fedora/listDatastreams/demo:5?xml=true

Listing Methods of an Object API-A-LITE listMethods)

URL syntax for the listMethods request:
http://hostname:port/fedora/listMethods/PID [/dateTime][?xml=BOOLEAN]

This syntax requests a list of methods available in the digital object.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
listMethods - a required parameter specifying the Fedora servlet path.
PID - a required parameter specifying the persistent identifier of the digital object.
dateTime - an optional dateTime parameter indicating dissemination of a version of the digital object at the specified point in time. Proper syntax is YYYY-MM-DDTHH:MM:SS where HH is 24-hour clock.
xml - an optional parameter indicating the requested output format. A value of "true" indicates a return type of text/xml; the absence of the xml parameter or a value of "false" indicates format is to be text/html.


Examples:

List the methods for a data object with PID of demo:5 as HTML:

	http://localhost:8080/fedora/listMethods/demo:5

List the methods for a data object with PID of demo:5 as XML:

	http://localhost:8080/fedora/listMethods/demo:5?xml=true

Getting Information about a Fedora Repository (API-A-LITE describeRepository)

URL syntax for the describeRepository request:
http://hostname:port/fedora/describe [?xml=BOOLEAN]

This syntax requests information about a Fedora repository, including repository name, version, base URL, PID syntax, OAI identifier syntax, admin emails, and sample request URLs. The xml parameter determines the type of output returned. If the parameter is omitted or has a value of "false", a MIME-typed stream consisting of an html table is returned providing a browser-savvy means of viewing the object profile. If the value specified is "true", then a MIME-typed stream consisting of XML is returned.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
describe - a required parameter specifying the Fedora servlet path for the describe request.
xml - an optional parameter indicating the requested output format. A value of "true" indicates a return type of text/xml; the absence of the xml parameter or a value of "false" indicates format is to be text/html.


Examples:

Get respository information using the "describe" request with results as HTML:

	http://localhost:8080/fedora/describe

Get respository information using the "describe" request with results as XML:

	http://localhost:8080/fedora/describe?xml=true

Running Disseminations using the Default Disseminator (API-A-LITE getDissemination with standard disseminations)

Each Fedora data object has a default disseminator that provides a simple means of accessing the data object's content without having to create a separate behavior definition and behavior mechanism object. Separate behavior definition and behavior mechanism objects can be added to extend the behaviors for an object beyond those behaviors provided by the default disseminator.

The default disseminator consists of a special internal behavior definition and behavior mechanism object that have the respective PIDs of fedora-system:3 and fedora-system:4. These special PIDs can be treated as ordinary behavior definition and behavior mechanism objects and used with both API-M, API-A, and API-A-Lite. The default disseminator provides five basic methods for viewing a data object's content. Although all of the default disseminator's methods can be accessed indirectly using the getObjectProfile method, they can also be disseminated using the special PID of fedora-system:3 for the default disseminator behavior definition object.

viewObjectProfile syntax:
http://hostname:port/fedora/get/PID/fedora-system:3/getObjectProfile

This syntax returns the data object's profile in XML format.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
get - a required parameter specifying the Fedora servlet path.
PID - PID of the object for which you wish to retrieve its object profile.
fedora-system:3 - PID of the behavior definition object for the default disseminator.
viewObjectProfile - method name to retrieve an object's profile in XML format.


Example:

Get the object profile of an object with a PID of demo:5 as HTML:

	http://localhost:8080/fedora/get/demo:5/fedora-system:3/viewObjectProfile

viewMethodIndex syntax:
http://hostname:port/fedora/get/PID/fedora-system:3/viewMethodIndex

This syntax retrieves the data object's method index in HTML format.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
get - a required parameter specifying the Fedora servlet path.
PID - PID of the object for which you wish to retrieve its object profile.
fedora-system:3 - PID of the behavior definition object for the default disseminator.
viewMethodIndex - method name to retrieve an object's method index in HTML format.


Example:

Get the method index for an object with a PID of demo:5 as HTML:

	http://localhost:8080/fedora/get/demo:5/fedora-system:3/viewMethodIndex

viewItemIndex syntax:
http://hostname:port/fedora/get/PID/fedora-system:3/viewItemIndex

This syntax retrieves the object's item index in HTML format.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
get - a required parameter specifying the Fedora servlet path.
PID - PID of the object for which you wish to retrieve its object profile.
fedora-system:3 - PID of the behavior definition object for the default disseminator.
viewItemIndex - method name to retrieve an object's item index in HTML format.


Example:

Get the item index for an object with a PID of demo:5 as HTML:

	http://localhost:8080/fedora/get/demo:5/fedora-system:3/viewItemIndex

viewDublinCore syntax:
http://hostname:port/fedora/get/PID/fedora-system:3/viewDublinCore

This syntax retrieves the object's item index in HTML format.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
get - a required parameter specifying the Fedora servlet path.
PID - PID of the object for which you wish to retrieve its object profile.
fedora-system:3 - PID of the behavior definition object for the default disseminator.
viewDublinCore - method name to retrieve an object's Dublin Core metadata in HTML format.


Example:

Get the Dublin Core metadata for an object with a PID of demo:5 as HTML:

	http://localhost:8080/fedora/get/demo:5/fedora-system:3/viewDublinCore

getItem syntax (deprecated):
http://hostname:port/fedora/get/PID/fedora-system:3/getItem?itemID=DSID

This syntax retrieves the data object's datastream using a specified datastream ID. The getItem syntax is now deprecated and the getDatastreamDissemination method should be used instead.

hostname - a required parameter specifying the hostname of the Fedora server.
port - a required parameter specifying the port number on which the Fedora server is running.
fedora - a required parameter specifying the Fedora servlet path.
get - a required parameter specifying the Fedora servlet path.
PID - PID of the object for which you wish to retrieve its object profile.
fedora-system:3 - PID of the behavior definition object for the default disseminator.
getItem - method name to retrieve an object's datastream using the specified datastream ID.
DSID - the datastream ID of the datastream you wish to retrieve.


Example:

Get the datastream with datastream ID of "DS1" from an object with a PID of demo:5:

	http://localhost:8080/fedora/get/demo:5/fedora-system:3/getItem?itemID=DS1

This syntax is now deprected. Instead use the getDatastreamDissemination syntax:

	http://localhost:8080/fedora/get/demo:5/DS1

Searching for Objects in the Repository (API-A-LITE findObjects)

The Fedora repository system also includes a search interface that enables searching across both System Metadata and user-defined Dublin Core metadata.Upon ingestion, metadata from the Fedora System Metadata section and the Dublin Core (DC) Metadata section of the object are indexed in a relational database, and may be searched using the search interface. The DC Metadata section is an optional Implementor-Defined XML Metadata datastream in the object, where the "Datastream ID" is DC, and the XML conforms to the schema at: http://www.openarchives.org/OAI/2.0/oai_dc.xsd. If such a datastream is not provided, Fedora will construct a default Dublin Core record using the label of the object as the dc:title value and the PID of the object as the dc:identifier value. The search interface provides both simple and advanced searching via a web page included with the repository software. All queries are case insensitive. Simple search enables queries of words and phrases occurring anywhere in an object's indexed metadata fields. Advanced Search enables fielded searching across any combination of metadata elements using string comparison operators (= and ~) for string fields, and value comparison operators ( =, >, ≥, <, ≤ ) for date fields (dc:date fields may be treated as both). The wildcards, * and ? may be used in any string-based query. The search interface can be accessed using the syntax:

http://hostname:port/fedora/search?{terms=TERMS|query=QUERY}[&maxResults=MAXRESULTS][&xml=true][&pid=true][&label=true][&fType=true][&cModel=true][&state=true][&ownerId=true][&cDate=true][&mDate=true][&dcmDate=true][&bDef=true][&bMech=true][&title=true][&creator=true][&subject=true][&description=true][&publisher=true][&contributor=true][&date=true][&type=true][&format=true][&identifier=true][&source=tru]e[&language=true][&relation=true][&coverage=true][&rights=true]

This syntax essentially performs a search upon the objects in the repository. It finds objects that meet the criteria specified in the request. The criteria are evaluated against an index of the repostory that contains unqualified Dublin Core and Fedora-specific metadata elements. The syntax provides a client with the ability to specify the search criteria as either a phrase (a simple keyword search), or as a set of name value pairs (a field-based search).

hostname - required hostname of the Fedora server.
port - required port number on which the Fedora server is running.
fedora - required name of the Fedora access service.
fedora - a required parameter specifying the Fedora servlet path.
search - a required parameter specifying the Fedora servlet path for the findObjects request.
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, fType, cModel, state, ownerId, cDate, mDate, dcmDate, bDef, bMech, 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. See example URLs at the end of this document for usage.
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.
xml - whether to return the result as an xml document. If this is given as true, the result will be in xml. Otherwise, the result will be provided in a simple html document.
pid - if true, the Fedora persistent identifier (PID) element of matching objects will be included in the response.
label - if true, the Fedora object label element of matching objects will be included in the response.
fType - if true, the Fedora object type element of matching objects will be included in the response.
cModel - if true, the Fedora content model element of matching objects will be included in the response.
state - if true, the Fedora object state element of matching objects will be included in the response.
ownerId - if true, the identity of users who own matching objects will be included in the response.
cDate - if true, the Fedora create date element of matching objects will be included in the response.
mDate - if true, the Fedora modified date of matching objects will be included in the response.
dcmDate - if true, the Dublin Core modified date element(s) of matching objects will be included in the response.
title - if true, the Dubliin Core title element(s) of matching objects will be included in the response.
creator - if true, the Dubliin Core creator element(s) of matching objects will be included in the response.
subject - if true, the Dubliin Core subject element(s) of matching objects will be included in the response.
description - if true, the Dubliin Core description element(s) of matching objects will be included in the response.
publisher - if true, the Dubliin Core publisher element(s) of matching objects will be included in the response.
contributor - if true, the Dubliin Core contributor element(s) of matching objects will be included in the response.
date - if true, the Dubliin Core date element(s) of matching objects will be included in the response.
type - if true, the Dubliin Core type element(s) of matching objects will be included in the response.
format - if true, the Dubliin Core format element(s) of matching objects will be included in the response.
identifier - if true, the Dubliin Core identifier element(s) of matching objects will be included in the response.
source - if true, the Dubliin Core source element(s) of matching objects will be included in the response.
language - if true, the Dubliin Core language element(s) of matching objects will be included in the response.
relation - if true, the Dubliin Core relation element(s) of matching objects will be included in the response.
coverage - if true, the Dubliin Core coverage element(s) of matching objects will be included in the response.
rights - if true, the Dubliin Core right element(s) of matching objects will be included in the response.


Examples:
      
Find objects in the repostiory that are indexed with the keyword "fedora." The result set should provide the PID and Dublin 
Core title elements for each object:

	http://localhost:8080/fedora/search?terms=fedora&pid=true&title=true

Find objects in the repository where the Dublin Core title contains the word "Rome" and the Dublin Core creator contains the 
word "Staples". The result set should provide the PID, plus the Dubin Core creator and title elements for each object:

	http://localhost:8080/fedora/search?query=title%7Erome%20creator%7Estaples&pid=true&title=true&creator=true

Find objects in the repository whose PID ends with the number 1. The result set should provide a max of 50 hits at a time, 
and it should provide the PID and Dubin Core title element for each object. The result set should be returned as xml:

	http://localhost:8080/fedora/search?query=pid%7E*1&maxResults=50&xml=true&pid=true&title=true

Resuming a Search for Objects in the Repository (API-A-LITE resumeFindObjects)

If a search was requested and the result set contains more "hits" than what was specified in the maxResults parameter of the search URL, then the following syntax is used to obtain the next group of items in the result set.

http://hostname:port/fedora/search ?sessionToken=SESSIONID[&xml=BOOLEAN]

hostname - required hostname of the Fedora server.
port - required port number on which the Fedora server is running.
fedora - required name of the Fedora access service
search - a required parameter specifying the Fedora servlet path for the findObjects request.
session Token - the identifier of the session to which the search results are being returned.
xml - boolean indicating whether to return the search results as xml. If this is given as true, the result will be in xml. Otherwise, the result will be provided in a simple HTML document.