Table of Contents

  1. Introduction
  2. Client Syntax

Introduction

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

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

Client Syntax

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.

          Example:
        
          Get respository information using the describe request as XML:

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

getDatastreamDissemination syntax:

http://hostname:port/fedora/get/PID/DSID[/dateTime]

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.

  • DSPID - identifier of the datastream.

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

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

            http://localhost:8080/fedora/get/demo:5/DC
 
        Get the thumbnail datastream (DS1) of demo object demo:5:

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

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

getObjectHistory syntax:

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

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

  • PID - required 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
      

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.SSSZ where HH is 24-hour clock and SSS is milliseconds.

  • 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
      

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=true][&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.

        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
      

listDatastreams syntax:

http://hostname:port/fedora/listDatastreams/ PID[/dateTime][?xml=BOOLEAN]

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

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

  • listDatastreams - 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.SSSZ where HH is 24-hour clock and SSS is milliseconds.

  • 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
      

listMethods syntax:

http://hostname:port/fedora/listMethods/ PID[/dateTime][?xml=BOOLEAN]

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

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.

      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