Web Exposure of the Fedora™ Access Service

Software Release 1.2.1

Fedora™ Development Team

$Id: webexp.dbx,v 1.16 2004/04/16 12:57:45 rlw Exp $


Table of Contents

Web Exposure
Running Disseminations (API-A-LITE getDissemination)
Getting an Object Profile (API-A-LITE getObjectProfile)
Getting Information about a Fedora Repository (API-A-LITE describeRepository)
Running Disseminations using the Default Disseminator (API-A-LITE getDissemination with standard disseminations)
Searching for Objects in the Repository (API-A-LITE findObjects)
Resuming a Search for Objects in the Repository (API-A-LITE resumeFindObjects)

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 - required name of the Fedora access service.

  • 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 where HH is 24-hour clock.

  • 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 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 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 - 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.

  • 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 getObjectProfile method of API-A-Lite actually uses the getObjectProfile and viewObjectProfile methods of the default disseminator to retrieve an object’s profile. The default disseminator provides seven basic methods for accessing and 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.

getObjectProfile syntax:

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

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

  • 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 – 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.

  • getObjectProfile – method name to retrieve an object’s profile in XML format.

Examples:

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

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

viewObjectprofile syntax:

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

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

  • 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 – 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 HTML format.

Examples:

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

getMethodIndex syntax:

http://hostname:port/fedora/get/PID/fedora-system:3/getMethodIndex

This syntax retrieves the data object’s method index in XML format.

  • 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 – 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.

  • getMethodIndex – method name to retrieve an object’s method index in XML format.

Examples:

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

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

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 - 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 – 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.

getItemIndex syntax:

http://hostname:port/fedora/get/PID/fedora-system:3/getItemIndex

This syntax retrieves the data object’s item index in XML format.

  • 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 – 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.

  • getItemIndex – method name to retrieve an object’s item index in XML format.

viewItemIndex syntax:

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

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

  • 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 – 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.

Examples:

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

getItem syntax:

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.

  • 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 – 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.

Examples:

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

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.

  • fedora - a required parameter specifying the Fedora servlet path.

  • search - a required parameter specifying the Fedora servlet path for the findObjects request.

  • sessionToken - 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.