Table of Contents |
---|
Introduction
The Fedora REST API exposes a subset of the Fedora Access and Management APIs as a RESTful (Representational State Transfer) Web Service. For release 3.2, the Fedora REST API has been upgraded to Beta status. With this change the REST API is no longer optional, it is enabled by default as are all of the other Fedora APIs. The primary reasons behind Beta status are the need for more robust testing, as well as the understanding that in a future release the REST API will likely subsume API-A-Lite and API-M-Lite, thus changing the API somewhat.
For examples of how to use the REST API programmatically, please refer to the TestRESTAPI test class (http://fedora-commons.svn.sourceforge.net/viewvc/*checkout*/fedora-commons/fedora/tags/release-3.0/src/test/junit/fedora/test/api/TestRESTAPI.java).
Warning | ||
---|---|---|
| ||
Due to an outstanding bug FCREPO-849, if you use Managed Content for DC, RELS-EXT or RELS-INT then please make sure these datastreams are versionable (the default setting for versionable is "true", so if you haven't specified this datastream property then you are safe). Ensure that you don't inadvertently set this property to "false" for these datastreams when using the API methods. |
Info | ||
---|---|---|
| ||
The HTTP Response portion of each method description listed below indicates the response on success. Unsuccessful calls will produce non-200 response codes appropriate to the error case. If, however, your client software has difficulty processing non-200 responses (such as is the case with Adobe's Flash Player) adding the query parameter 'flash=true' to any method will ensure that all responses are in the 200 range. In the event of an error, the response code will be set to 200 and the response body will include the error message followed by "::ERROR". |
Info | ||
---|---|---|
| ||
If the client with which you are working does not support use of the PUT and/or DELETE HTTP methods but does allow you to set headers on the HTTP request, you can use POST replacement to make PUT and DELETE calls. To do this, simply set the X-HTTP-Method-Override request header to the correct method value (PUT or DELETE) and perform a POST request. Your request will be handled by the REST API as if it were a PUT or DELETE. |
Info | ||
---|---|---|
| ||
For release 3.3 the |
Info | ||
---|---|---|
| ||
The REST API requires that parameters - including path parameters - are URL-encoded. Particularly this is important if you have any PIDs that use escaped-octets in the PID name. In this case the "%" character should be URL-encoded as "%25", eg a PID "changeme:1234%2F56" should be URL-encoded as "changeme:1234%252F56". The ":" PID namespace separator character does not require URL-encoding as it has no special meaning when used in the path component of HTTP URIs; however some software library URL-encoding methods will URL-encode this to %3A - that's not a problem, both ":" and "%3A" will be accepted by the REST API. |
API-A Methods
describeRepository
Panel | ||||
---|---|---|---|---|
| ||||
Not implemented |
findObjects
Panel | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
URL Syntax /objects ? [terms | query] [maxResults] [resultFormat] [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 HTTP Response 200 Parameters
Examples /objects?terms=demo&pid=true&subject=true&label=true&resultFormat=xml /objects?query=title%7Erome%20creator%7Estaples&pid=true&title=true&creator=true /objects?query=pid%7E*1&maxResults=50&format=true&pid=true&title=true |
getDatastreamDissemination
Panel | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
URL Syntax /objects/{pid}/datastreams/{dsID}/content ? [asOfDateTime] [download] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/datastreams/DC/content /objects/demo:29/datastreams/DC/content?asOfDateTime=2008-01-01 |
getDissemination
Panel | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
URL Syntax /objects/{pid}/methods/{sdefPid}/{method} ? [method parameters] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/methods/demo:27/resizeImage?width=100 /objects/demo:SmileyEarring/methods/demo:DualResolution/fullSize |
getObjectHistory
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
URL Syntax /objects/{pid}/versions ? [format] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/versions /objects/demo:29/versions?format=xml |
getObjectProfile
Panel | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||
URL Syntax /objects/{pid} ? [format] [asOfDateTime] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29 /objects/demo:29?format=xml /objects/demo:29?asOfDateTime=2008-01-01 |
listDatastreams
Panel | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||
URL Syntax /objects/{pid}/datastreams ? [format] [asOfDateTime] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:35/datastreams /objects/demo:35/datastreams?format=xml&asOfDateTime=2008-01-01T05:15:00Z |
listMethods
Panel | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
URL Syntax
HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/methods /objects/demo:29/methods?format=xml&asOfDateTime=2008-01-01T05:15:00Z /objects/demo:29/methods/demo:27 /objects/demo:29/methods/demo:27?format=xml&asOfDateTime=2008-01-01T05:15:00Z |
resumeFindObjects
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
URL Syntax /objects ? [sessionToken] [all findObjects options] HTTP Method GET HTTP Response 200 Parameters
Examples /objects?terms=*&format=xml&pid=true&subject=true&label=true&sessionToken=xyz\\\\ |
API-M Methods
addDatastream
Panel | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
URL Syntax /objects/{pid}/datastreams/{dsID} ? [controlGroup] [dsLocation] [altIDs] [dsLabel] [versionable] [dsState] [formatURI] [checksumType] [checksum] [mimeType] [logMessage] HTTP Method POST HTTP Response 201 Parameters
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
Panel | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||
URL Syntax /objects/{pid}/relationships/new ? [subject] [predicate] [object] [isLiteral] [datatype] HTTP Method POST HTTP Response 200 Parameters
Examples POST /objects/demo:29/relationships/new?subject=info%3afedora%2fdemo%3a29%2fDC&predicate=http%3a%2f%2fwww.example.org%2frels%2fname&object=dublin%20core&isLiteral=true |
compareDatastreamChecksum
Panel | ||||
---|---|---|---|---|
| ||||
See #getDatastream |
export
Panel | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
URL Syntax /objects/{pid}/export ? [format] [context] [encoding] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/export /objects/demo:29/export?context=migrate |
getDatastream
Anchor | ||||
---|---|---|---|---|
|
Panel | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
URL Syntax /objects/{pid}/datastreams/{dsID} ? [asOfDateTime] [format] [validateChecksum] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/datastreams/DC /objects/demo:29/datastreams/DC?format=xml /objects/demo:29/datastreams/DC?format=xml&validateChecksum=true |
getDatastreamHistory
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
URL Syntax /objects/{pid}/datastreams/{dsid}/history ? [format] HTTP Method GET HTTP Response 200 Parameters
Examples GET: /objects/changeme:1/datastreams/DC/history GET: /objects/changeme:1/datastreams/DC/history?format=xml |
getDatastreams
Panel | ||||
---|---|---|---|---|
| ||||
Not implemented |
getNextPID
Panel | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||
URL Syntax /objects/nextPID ? [numPIDs] [namespace] [format] HTTP Method POST HTTP Response 200 Parameters
Examples POST: /objects/nextPID POST: /objects/nextPID?numPIDs=5&namespace=test&format=xml |
getObjectXML
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
URL Syntax /objects/{pid}/objectXML HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/objectXML |
getRelationships
Panel | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
URL Syntax /objects/{pid}/relationships ? [subject] [predicate] [format] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/relationships /objects/demo:29/relationships?subject=info%3afedora%2fdemo%3a29%2fDC |
ingest
Panel | ||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||
URL Syntax /objects/ [{pid}| new] ? [label] [format] [encoding] [namespace] [ownerId] [logMessage] [ignoreMime] HTTP Method POST HTTP Response 201 Request Content text/xml Parameters
Notes Executing this request with no request content will result in the creation of a new, empty object (with either the specified PID or a system-assigned PID). The new object will contain only a minimal DC datastream specifying the dc:identifier of the object. Examples POST: /objects/new POST: /objects POST: /objects/new?namespace=demo POST: /objects/test:100?label=Test |
modifyDatastream
Panel | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
URL Syntax /objects/{pid}/datastreams/{dsID} ? [dsLocation] [altIDs] [dsLabel] [versionable] [dsState] [formatURI] [checksumType] [checksum] [mimeType] [logMessage] [ignoreContent] [lastModifiedDate] HTTP Method PUT HTTP Response 200 Parameters
Examples PUT: /objects/demo:35/datastreams/HIGH (with Multipart file) PUT: /objects/demo:35/datastreams/HIGH?dsLocation=http://example:80/highDS?logMessage=Update |
modifyObject
Panel | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||
URL Syntax /objects/{pid} ? [label] [ownerId] [state] [logMessage] [\lastModifiedDate] HTTP Method PUT HTTP Response 200 Parameters
Examples PUT: /objects/demo:29?label=Updated PUT: /objects/demo:29?state=D?logMessage=Deleted |
purgeDatastream
Panel | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
URL Syntax /objects/{pid}/datastreams/{dsID} ? [startDT] [endDT] [logMessage] HTTP Method DELETE HTTP Response 200 with a string array of the date-time stamps of the versions purged Parameters
Examples DELETE: /objects/demo:35/datastreams/HIGH |
purgeObject
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
URL Syntax /objects/{pid} ? [logMessage] HTTP Method DELETE HTTP Response 204 Parameters
Examples DELETE: /objects/demo:29 |
purgeRelationship
Panel | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||
URL Syntax /objects/{pid}/relationships ? [subject] [predicate] [object] [isLiteral] [datatype] HTTP Method DELETE HTTP Response 200 Return body Text indicating if the relationship was successfully purged: Parameters
Examples DELETE /objects/demo:29/relationships?subject=info%3afedora%2fdemo%3a29%2fDC&predicate=http%3a%2f%2fwww.example.org%2frels%2fname&object=dublin%20core&isLiteral=true |
setDatastreamState
Panel | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||
URL Syntax /objects/{pid}/datastreams/{dsID} ? [dsState] HTTP Method PUT HTTP Response 200 Parameters
Examples PUT: /objects/demo:35/datastreams/HIGH?dsState=D |
setDatastreamVersionable
Panel | |||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||
URL Syntax /objects/{pid}/datastreams/{dsID} ? [versionable] HTTP Method PUT HTTP Response 200 Parameters
Examples PUT: /objects/demo:35/datastreams/HIGH?versionable=false Validate
URL Syntax /objects/{pid}/validate ? [asOfDateTime] HTTP Method GET HTTP Response 200 (OK) if the validation could be carried out (even if the object is not valid) 404 If some object or datastream could not be carried out 401 If the user credentials was insufficient 400 If the parameters are misformed 409 If one of the relevant objects were locked 500 If something else failed on the server Return Body XML, adhering to this schema
Parameters
Examples GET /objects/validate/demo:29?asOfDateTime=2008-01-01
GET /objects/validate/demo:fail
|
Utility Methods
Upload
Panel | ||||
---|---|---|---|---|
| ||||
URL Syntax /upload HTTP Method POST HTTP Response 202 and a URI for the uploaded file Parameters Multipart file as request content Examples POST: /upload (with Multipart file) |
WADL
When running your own Fedora server, the REST API WADL is available at /objects/application.wadl.
Example:
Panel |
---|