Fedora™ API-A-Lite Interface Client User Documentation

Software Release 1.2.1

Fedora™ Development Team

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


Table of Contents

Introduction
Client Syntax

Introduction

The Fedora API-A-Lite interface is implemented as an HTTP service that consists of the following methods:

  • getDissemination - gets the specified dissemination request

  • getObjectProfile - gets the Object Profile of the specified object

  • describeRepository - provides information about the Fedora repository server, including name, version, base URL

  • findObjects (search) - performs a search on the respository given specified search criteria and returns a result set for matching objects

  • resumeFindObjects (search) - gets the next set of items ("hits") in a search result set. Used when a prior findObjects request specified that the result set should be returned with a maximum number of hits at a time.

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

Client Syntax

getDissemination syntax:

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

getObjectProfile syntax:

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

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

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

describeRepository syntax:

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.

findObjects 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, each matching objects' owner id 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.

resumeFindObjects syntax:

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

This syntax requests the next members of a result set from a prior invocation of a findObjects request. If the findObjects request was run and there are more "hits" in the result set than the maxResults setting on the findObjects request, then the resumeFindObjects request is used to obtain the next group of items in the result set.

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

Examples

Get the Dissemination for a data object with a PID of demo:5 and associated behavior definition object with a PID of demo:1 and methodName of getThumbnail

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

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

Get respository information using the describe request as XML:

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

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