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.
...
Info |
---|
title | 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
describeRepository
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
Not implemented |
...
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
URL Syntax /objects/{pid}/datastreams/{dsID}/content ? [asOfDateTime] [download] HTTP Method GET HTTP Response 200 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 | download | If true, a content-disposition header value "attachment" will be included in the response, prompting the user to save the datastream as a file. A content-disposition header value "inline" will be used otherwise. The filename used in the header is generated by examining in order: RELS-INT for the relationship fedora-model:downloadFilename, the datastream label, and the datastream ID. The file extension (apart from where the filename is specified in RELS-INT) is determined from the MIMETYPE. The order in which these filename sources are searched, and whether or not to generate an extension from the MIMETYPE, is configured in fedora.fcfg. The file used to map between MIMETYPEs and extensions is mime-to-extensions.xml located in the server config directory. | | |
Examples /objects/demo:29/datastreams/DC/content /objects/demo:29/datastreams/DC/content?asOfDateTime=2008-01-01 |
...
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
URL Syntax /objects/{pid}/methods/{sdefPid}/{method} ? [method parameters] HTTP Method GET HTTP Response 200 Parameters Name | Description | Default | Options |
---|
{pid} | persistent identifier of the digital object | | | {sdefPid} | persistent identifier of the sDef defining the methods | | | {method} | method to invoke | | | method parameters | any parameters required by the method | | |
Examples /objects/demo:29/methods/demo:27/resizeImage?width=100 /objects/demo:SmileyEarring/methods/demo:DualResolution/fullSize |
...
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
URL Syntax /objects ? [sessionToken] [all findObjects options] HTTP Method GET HTTP Response 200 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\\\\ |
API-M Methods
addDatastream
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
URL Syntax /objects/{pid}/datastreams/{dsID} ? [controlGroup] [dsLocation] [altIDs] [dsLabel] [versionable] [dsState] [formatURI] [checksumType] [checksum] [mimeType] [logMessage] HTTP Method POST HTTP Response 201 Parameters Name | Description | Default | Options |
---|
{pid} | persistent identifier of the digital object | | | {dsID} | datastream identifier | | | controlGroup | one of "X", "M", "R", or "E" (Inline *X*ML, *M*anaged Content, *R*edirect, or *E*xternal 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" (*A*ctive, *I*nactive, *D*eleted) | 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 | checksum | the value of the checksum represented as a hexadecimal string | | | mimeType | the MIME type of the content being added, this overrides the Content-Type request header | | | logMessage | a message describing the activity being performed | | | multipart file as request content | 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
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
URL Syntax /objects/{pid}/relationships/new ? [subject] [predicate] [object] [isLiteral] [datatype] HTTP Method POST HTTP Response 200 Parameters Name | Description | Default | Options |
---|
{pid} | persistent identifier of the digital object | | | subject | subject of the relationship. Either a URI for the object or one of its datastreams | URI of this object | | predicate | predicate of the relationship | | | object | object of the relationship | | | isLiteral | true if the object of the relationship is a literal, false if it is a URI | | true, false | datatype | if the object is a literal, the datatype of the literal (optional) | | |
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 |
...
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
URL Syntax /objects/{pid}/datastreams/{dsid}/versions history ? [format] HTTP Method GET HTTP Response 200 Parameters Name | Description | Default | Options |
---|
format | the preferred output format | html | xml, html |
Examples GET: /objects/changeme:1/datastreams/DC/versionshistory GET: /objects/changeme:1/datastreams/DC/versionshistory?format=xml |
getDatastreams
...
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
URL Syntax /objects/ [{pid}| new] ? [label] [format] [encoding] [namespace] [ownerId] [logMessage] [ignoreMime] HTTP Method POST HTTP Response 201 Request Content text/xml Parameters Name | Description | Default | Options |
---|
{pid} | persistent identifier of the object to be created | new (see below) | | new | indicator that either a new PID should be created for this object or that the PID to be used is encoded in the XML included as the body of the request | | | 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.0, info:fedora/fedora-system:METSFedoraExt-1.1, info:fedora/fedora-system:METSFedoraExt-1.0, info:fedora/fedora-system:ATOM-1.1, info:fedora/fedora-system:ATOMZip-1.1 | | encoding | the encoding of the XML to be ingested. If this is specified, and given as anything other than UTF-8, you must ensure that the same encoding is declared in the XML. For example, if you specify "ISO-88591" as the encoding, the XML should start with: <?xml version="1.0" encoding="ISO-8859-1"?> | UTF-8 | | namespace | the namespace to be used to create a PID for a new empty object; if object XML is included with the request, the namespace parameter is ignored | 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 | | | ignoreMime | indicates that the request should not be checked to ensure that the content is XML prior to attempting an ingest. This is provided to allow for client applications which do not indicate the correct Content-Type when submitting a request. | false | true, false | XML file as request content | file to be ingested as a new object | | |
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 |
...
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
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 Name | Description | Default | Options |
---|
{pid} | persistent identifier of the digital object | | | {dsID} | datastream identifier | | | dsLocation | location of datastream content | | | altIDs | alternate identifiers for the datastream | | | dsLabel | the label for the datastream | | | versionable | enable versioning of the datastream | the "versionable" property of the existing datastream | true, false | dsState | one of "A", "I", "D" (*A*ctive, *I*nactive, *D*eleted) | 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 | checksum | the value of the checksum represented as a hexadecimal string | | | mimeType | the MIME type of the content being added, this overrides the Content-Type request header | | | logMessage | a message describing the activity being performed | | | ignoreContent | tells the request handler to ignore any content included as part of the request, indicating that you do not intend to update the datasteam content. This is primarily provided to allow the use of client tools which always require content to be included as part of PUT requests. | false | true, false | lastModifiedDate | date/time of the last (known) modification to the datastream, if the actual last modified date is later, a 409 response is returned | | | multipart file as request content | 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
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
URL Syntax /objects/{pid} ? [label] [ownerId] [state] [logMessage] [\lastModifiedDate] HTTP Method PUT HTTP Response 200 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 - *A*ctive, *I*nactive, or *D*eleted | A | A, I, D | logMessage | a message describing the activity being performed | | | lastModifiedDate | date/time of the last (known) modification to the datastream, if the actual last modified date is later, a 409 response is returned | | |
Examples PUT: /objects/demo:29?label=Updated PUT: /objects/demo:29?state=D?logMessage=Deleted |
...
Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
|
URL Syntax /objects/{pid}/datastreams/{dsID} ? [versionable] HTTP Method PUT HTTP Response 200 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 Validate Panel |
---|
bgColor | white |
---|
borderStyle | none |
---|
| |
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 Code Block |
---|
<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 Name | Description | Default | Options |
---|
{pid} | persistent identifier of the digital object | | | asOfDateTime | indicates that the result should be relative to the digital object and the repository as it existed at the given date and time | | yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ |
Examples GET /objects/validate/demo:29?asOfDateTime=2008-01-01 Returns HTTP 200 with the body Code Block |
---|
<?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 Returns HTTP 200 with the body. Here the error was a mispelled element in the DC datastream, "dc:titel" Code Block |
---|
<?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> |
|
...