Table of Contents

  1. Introduction
  2. API-A Methods
    1. describeRepository
    2. findObjects
    3. getDatastreamDissemination
    4. getDissemination
    5. getObjectHistory
    6. getObjectProfile
    7. listDatastreams
    8. listMethods
    9. resumeFindObjects
  3. API-M Methods
    1. addDatastream
    2. addRelationship
    3. compareDatastreamChecksum
    4. export
    5. getDatastream
    6. getDatastreamHistory
    7. getDatastreams
    8. getNextPID
    9. getObjectXML
    10. getRelationships
    11. ingest
    12. modifyDatastream
    13. modifyObject
    14. purgeDatastream
    15. purgeObject
    16. purgeRelationship
    17. setDatastreamState
    18. setDatastreamVersionable
  4. WADL
  1. Introduction

    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.

  2. API-A Methods

    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


  3. API-M Methods

    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

  4. WADL

    1. Offline For reference, an offline copy of the REST WADL is available here.
    2. Online When running your own Fedora server, an online copy of the REST WADL will be made publicly available at /objects/application.wadl. For example: http://localhost:8080/fedora/objects/application.wadl