IntroductionThe 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). Ensure DC, RELS-EXT and RELS-INT are versionable if using Managed Content 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. 2xx Responses only please 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". POST Replacement 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. Removal of .xml shortcut For release 3.3 the URL-Encoding 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. 400 Responses for invalid content If the contents of your request are invalid, and Fedora produces a validation error (eg invalid FOXML on ingest) the HTTP status code is 400. Previous versions of Fedora reported 500 - Server Failure for validation errors. API-A Methods
describeRepositoryNot implemented findObjectsURL 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 getDatastreamDisseminationURL 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 getDisseminationURL 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 getObjectHistoryURL Syntax /objects/{pid}/versions ? [format] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/versions /objects/demo:29/versions?format=xml getObjectProfileURL 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 listDatastreamsURL 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 listMethodsURL 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 resumeFindObjectsURL 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
addDatastreamURL 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 addRelationshipURL 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 compareDatastreamChecksumSee #getDatastream exportURL 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 getDatastreamURL 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 getDatastreamHistoryURL 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 getDatastreamsURL Syntax /objects/{pid}/datastreams ? [profiles] [asOfDateTime] HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:35/datastreams?profiles=true /objects/demo:35/datastreams?profiles=true&asOfDateTime=2012-08-03T10:02:00.169Z getNextPIDURL 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 getObjectXMLURL Syntax /objects/{pid}/objectXML HTTP Method GET HTTP Response 200 Parameters
Examples /objects/demo:29/objectXML getRelationshipsURL 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 ingestURL 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 modifyDatastreamURL 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 modifyObjectURL 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 purgeDatastreamURL 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 purgeObjectURL Syntax /objects/{pid} ? [logMessage] HTTP Method DELETE HTTP Response 204 Parameters
Examples DELETE: /objects/demo:29 purgeRelationshipURL 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 setDatastreamStateURL Syntax /objects/{pid}/datastreams/{dsID} ? [dsState] HTTP Method PUT HTTP Response 200 Parameters
Examples PUT: /objects/demo:35/datastreams/HIGH?dsState=D setDatastreamVersionableURL Syntax /objects/{pid}/datastreams/{dsID} ? [versionable] HTTP Method PUT HTTP Response 200 Parameters
Examples PUT: /objects/demo:35/datastreams/HIGH?versionable=false ValidateURL 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 <xs:schema targetNamespace="http://www.fedora.info/definitions/1/0/access/" xmlns="http://www.fedora.info/definitions/1/0/access/" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xs:element name="validation"> <xs:complexType> <xs:sequence> <xs:element ref="asOfDateTime"/> <xs:element ref="contentModels"/> <xs:element ref="problems"/> <xs:element ref="datastreamProblems"/> </xs:sequence> <xs:attribute name="pid" use="required"> <xs:simpleType> <xs:restriction base="xs:string"/> </xs:simpleType> </xs:attribute> <xs:attribute name="valid" use="required"> <xs:simpleType> <xs:restriction base="xs:boolean"/> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> <xs:element name="asOfDateTime"> <xs:simpleType> <xs:restriction base="xs:dateTime"/> </xs:simpleType> </xs:element> <xs:element name="contentModels"> <xs:complexType> <xs:sequence> <xs:element name="model" minOccurs="0" maxOccurs="unbounded" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="problems"> <xs:complexType> <xs:sequence> <xs:element name="problem" minOccurs="0" maxOccurs="unbounded" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="datastreamProblems"> <xs:complexType> <xs:sequence> <xs:element ref="datastream" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="datastream"> <xs:complexType> <xs:sequence> <xs:element name="problem" minOccurs="0" maxOccurs="unbounded" type="xs:string"/> </xs:sequence> <xs:attribute name="datastreamID" use="required"> <xs:simpleType> <xs:restriction base="xs:string"/> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> </xs:schema> Parameters
Examples GET /objects/validate/demo:29?asOfDateTime=2008-01-01 <?xml version="1.0" encoding="UTF-8"?> <validation pid="demo:29" valid="true"> <asOfDateTime>2008-01-01T00:00:00.000Z</asOfDateTime> <contentModels> <model>info:fedora/fedora-system:FedoraObject-3.0</model> </contentModels> <problems> </problems> <datastreamProblems> </datastreamProblems> </validation> GET /objects/validate/demo:fail <?xml version="1.0" encoding="UTF-8"?> <validation pid="demo:fail" valid="false"> <asOfDateTime></asOfDateTime> <contentModels> <model>info:fedora/fedora-system:FedoraObject-3.0</model> </contentModels> <problems> </problems> <datastreamProblems> <datastream datastreamID="DC"> <problem>Encountered schema validation error while parsing datastream 'DC' with the schema from content model 'fedora-system:FedoraObject-3.0'. The error was 'cvc-complex-type.2.4.a: Invalid content was found starting with element 'dc:titel'. One of '{"http://purl.org/dc/elements/1.1/":title, "http://purl.org/dc/elements/1.1/":creator, "http://purl.org/dc/elements/1.1/":subject, "http://purl.org/dc/elements/1.1/":description, "http://purl.org/dc/elements/1.1/":publisher, "http://purl.org/dc/elements/1.1/":contributor, "http://purl.org/dc/elements/1.1/":date, "http://purl.org /dc/elements/1.1/":type, "http://purl.org/dc/elements/1.1/":format, "http://purl.org/dc/elements/1.1/":identifier, "http://purl.org/dc/elements/1.1/":source, "http://purl.org/dc/elements/1.1/":language, "http://purl.org/dc/elements/1.1/":relation, "http://purl.org/dc/elements/1.1/":coverage, "http://purl.org/dc/elements/1.1/":rights}' is expected.'</problem> </datastream> </datastreamProblems> </validation> Utility MethodsUploadURL 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) WADLWhen running your own Fedora server, the REST API WADL is available at /objects/application.wadl. Example: |