Overview
Introduction
The Fedora 4 HTTP API is generally a RESTful API. HTTP methods like GET, PUT, POST and DELETE are implemented on most resource paths. The API also relies heavily on content negotiation to deliver context-appropriate responses, and a HATEOAS-driven text/html response (providing a decent GUI experience on top of the repository).
The Fedora 4 RDF-based responses may be serialized as:
- application/n3 (or text/rdf+n3 or text/n3)
- application/n-quads
- application/n-triples
- application/rdf+json
- application/rdf+xml
- text/trig
- text/turtle
The text/html response also includes embedded RDFa markup.
The API is based loosely around the Linked Data Platform 1.0 Architecture, which:
[...] describes the use of HTTP for accessing, updating, creating and deleting resources from servers that expose their resources as Linked Data. It provides clarifications and extensions of the rules of Linked Data [LINKED-DATA]:
- Use URIs as names for things
- Use HTTP URIs so that people can look up those names
- When someone looks up a URI, provide useful information, using the standards (RDF*, SPARQL)
- Include links to other URIs, so that they can discover more things
Changes planned
- Asynchronous API support
Endpoints
Resources
Repository objects can be loosely divided into two classes of resources:
- Object and containers ("fedora:object"), containing RDF properties and 0 or more child nodes
- Binaries, containing any binary payload (roughly corresponding to Fedora 3 datastreams)
Objects
Request URI: /path/to/some/resource
Methods: GET, POST, PUT, PATCH, DELETE, MOVE, COPY
GET Retrieve all triples for the resource
Query Parameters:
NON-MEMBER-PROPERTIES By default, we include triples for all member resources, in addition to triples about the given node. Setting this to true will exclude member resources from the result.
OFFSET Pagination control for member resources
LIMIT Pagination control for member resources
Request Headers:
ACCEPT text/turtle, text/rdf+n3, application/n3, text/n3, application/rdf+xml, application/json+rdf, application/n-triples, text/html
IF-NONE-MATCHIF-MODIFIED-SINCE
Example (1):
curl -H "Accept: text/turtle" "http://localhost:8080/rest/"
Response:
Status: 200 OK Headers: Content-Type: text/turtle Cache-Control: Last-Modified-At: 2013-01-01T01:23:45Z Link: http://localhost:8080/rest/?offset=0&limit=10;rel="first" Link: http://www.w3.org/ns/ldp/Resource;rel="type" Accept-Patch: application/sparql-update Body: <http://localhost:8080/rest/> a <http://www.w3.org/ns/ldp#Container> , <http://www.w3.org/ns/ldp#Page> ; <http://www.w3.org/ns/ldp#membersInlined> "true" ; <http://www.w3.org/ns/ldp#membershipObject> <http://www.w3.org/ns/ldp#MemberSubject> ; <http://www.w3.org/ns/ldp#membershipPredicate> <http://fedora.info/definitions/v4/repository#hasChild> ; <http://www.w3.org/ns/ldp#membershipSubject> <http://localhost:8080/rest/> ; <http://www.w3.org/ns/ldp#pageOf> <http://localhost:8080/rest/> ; <http://fedora.info/definitions/v4/rest-api#exportsAs> <http://localhost:8080/rest//fcr:export?format=jcr/xml> ; <http://fedora.info/definitions/v4/rest-api#hasNamespaces> <http://localhost:8080/rest/fcr:namespaces> ; <http://fedora.info/definitions/v4/rest-api#hasTransactionProvider> <http://localhost:8080/rest/fcr:tx> ; <http://fedora.info/definitions/v4/rest-api#hasWorkspaces> <http://localhost:8080/rest/fcr:workspaces> ; <http://microformats.org/wiki/rel-sitemap> <http://localhost:8080/rest/sitemap> ;
Example (2):
curl -H "Accept: text/turtle" "http://localhost:8080/rest/path/to/resource"
Response:
Status: 200 OK Headers: ETag: "d98e86c48a3e31857f5311f51ad7a2e13a7cedee" Content-Type: text/turtle Cache-Control: must-revalidate Last-Modified: Fri, 15 Nov 2013 23:31:07 +0000 Link: http://localhost:8080/rest/path/to/resource/?offset=0&limit=10;rel="first" Link: http://www.w3.org/ns/ldp/Resource;rel="type" Accept-Patch: application/sparql-update Body: <http://localhost:8080/rest/path/to/resource> a <http://fedora.info/definitions/v4/rest-api#resource> , <http://fedora.info/definitions/v4/rest-api#object> , <http://www.w3.org/ns/ldp#Container> , <http://www.w3.org/ns/ldp#Page> ; <http://fedora.info/definitions/v4/repository#uuid> "e8baa85c-f05a-49e8-9578-9adef92ac60d"^^<http://www.w3.org/2001/XMLSchema#string> ; <http://www.w3.org/ns/ldp#inlinedResource> <http://localhost:8080/rest/path/to> ; <http://www.w3.org/ns/ldp#membersInlined> "true" ; <http://www.w3.org/ns/ldp#pageOf> <http://localhost:8080/rest/path/to/resource> . <http://fedora.info/definitions/v4/rest-api#exportsAs> <http://localhost:8080/rest/path/to/resource/fcr:export?format=jcr/xml> ; <http://fedora.info/definitions/v4/rest-api#hasVersions> <http://localhost:8080/rest/path/to/resource/fcr:versions> ; <http://fedora.info/definitions/v4/repository#created> "2013-11-15T23:31:07.275Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ; <http://fedora.info/definitions/v4/repository#createdBy> "bypassAdmin"^^<http://www.w3.org/2001/XMLSchema#string> ; <http://fedora.info/definitions/v4/repository#hasParent> <http://localhost:8080/rest/path/to> ; <http://fedora.info/definitions/v4/repository#lastModified> "2013-11-15T23:31:07.268Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ;
Status:
200 OK
304 Not Modified
404 Not Found
POST Create a new node at the given path
Create a new node at the given path, and recursively create any missing parent elements.
Query Parameters:
MIXIN (Optional; values: fedora:object, fedora:datastream) Explicitly create an object or datastream, instead of inferring it from the request body
Example (1):
curl -X POST "http://localhost:8080/rest/some/path/to/a/new/resource"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/path/to/a/new/resource
Example (2):
curl -X POST "http://localhost:8080/rest/some/path/to/a/new/resource?mixin=fedora:datastream" # Create a fedora:datastream
Status:
201 Created
POST Create a new node as a child of the given node
If the given resource path exists, a POST to that path will create a new node as a child of the given resource using a generated identifier.
Request Headers:
SLUG Use the slug header when creating the new resource (see AtomPub slug header). If no slug is provided, the identifier will be automatically generated.
The slug you provide does not guarantee the location of the created node. Clients must check the Location header for the path to the created resource. For full control over the generated path, see POST Create a new node at the given path (link me!)
Query Parameters:
MIXIN (Optional; values: fedora:object, fedora:datastream) Explicitly create an object or datastream, instead of inferring it from the request body
Example (1):
curl -X POST "http://localhost:8080/rest/this/node/already/exists"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/this/node/already/exists/some/generated/identifier
Example (2):
curl -X POST -H "Slug: new-node-name" "http://localhost:8080/rest/this/node/already/exists"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/this/node/already/exists/new/node/name
Status:
201 Created
POST Create a new node and populate some properties
In addition to creating a new node, add the given properties to the object
An RDF payload can be combined with any of the above forms.
RDF will be interpreted using the current resource as the base URI (e.g. <> will be expanded to the current URI)
Query Parameters:
CHECKSUM
Example:
curl -X POST -H "Content-Type: text/turtle" "http://localhost:8080/rest/node/to/create" -d "@body.rdf" Request Body: <> dc:title "some-resource-title"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/node/to/create
Status:
201 Created
POST Create a new node and execute a SPARQL-Update query
In addition to creating a new node, execute a SPARQL-Update query against the newly created node.
Query Parameters:
CHECKSUM
RDF will be interpreted using the current resource as the base URI (e.g. <> will be expanded to the current URI)
Example:
curl -X POST -H "Content-Type: application/sparql-update" "http://localhost:8080/rest/node/to/create" -d "@body.rdf" Request Body: INSERT { <> dc:title "some-resource-title" . } WHERE { }
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/node/to/create
Status:
201 Created
POST Create a new resource with binary content
If the binary content is RDF or a SPARQL-Update query, see Binary Content for an alternative way to create content
Query Parameters:
CHECKSUM Checksum of the binary content (in the form urn:sha1:<sha-hash>). If the checksum doesn't match, an error will be returned.
Header Parameters:
CONTENT-DISPOSITION The filename provided in the content disposition header will be stored in a premis:hasOriginalName property.
Example (1):
curl -X POST "http://localhost:8080/rest/binary/resource/to/create" -d "@picture.jpg"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/binary/resource/to/create/fcr:content
Example (2):
curl -X POST "http://localhost:8080/rest/binary/resource/to/create?checksum=urn:sha1:cb1a576f22e8e3e110611b616e3e2f5ce9bdb941" -d "@picture.jpg"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/binary/resource/to/create/fcr:content
Example (3):
curl -X POST "http://localhost:8080/rest/binary/resource/to/create?checksum=urn:sha1:checksumdoesntmatch" -d "@picture.jpg"
Response:
Status: 409 Conflict Error: Checksum Mismatch of cb1a576f22e8e3e110611b616e3e2f5ce9bdb941 and urn:sha1:checksumdoesntmatch
By convention, binary content is accessed using the REST endpoint path/to/resource/fcr:content.
Status:
201 Created
409 Conflict
PUT Modify the triples associated with the resource
Replace the existing triples for a resource with the triples provided in the request body.
Some resource properties are repository managed and cannot be removed or modified. Any attempt to do so may result in a 4xx error.
RDF will be interpreted using the current resource as the base URI (e.g. <> will be expanded to the current URI)
Request Headers:
CONTENT-TYPE text/turtle, text/rdf+n3, application/n3, text/n3, application/rdf+xml, application/json+rdf, application/n-triples, text/html
IF-MATCHIF-UNMODIFIED-SINCE
Query Parameters:
CHECKSUM Checksum of the binary content (in the form urn:sha1:<sha-hash>). If the checksum doesn't match, an error will be returned.
Example:
curl -X POST -H "Content-Type: text/turtle" "http://localhost:8080/rest/node/to/update" -d "@new-triples.rdf" Request Body: <> dc:title "some-resource-title" .
Response:
Status: 204 No Content
Status:
204 No Content
412 Precondition Failed
PATCH with SPARQL-Update
Request Headers:
IF-MATCHIF-UNMODIFIED-SINCE
Example:
curl -X PATCH -H "Content-Type: application/sparql-update" "http://localhost:8080/rest/node/to/update" -d "@body.rdf" Request Body: INSERT { <> dc:title "some-resource-title" . } WHERE { }
Response:
Status: 204 No Content
Status:
204 No Content
412 Precondition Failed
DELETE Delete a resource
Example:
curl -X DELETE "http://localhost:8080/rest/node/to/delete"
Response:
Status: 204 No Content
Status:
204 No Content
MOVE Move a resource (and its subtree) to a new location
Example (1):
curl -X MOVE -H "Destination: http://localhost:8080/rest/new/path/to/node" "http://localhost:8080/rest/path/to/node"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/new/path/to/node
Example (2):
curl -X MOVE -H "Destination: http://duraspace.org/some/path" "http://localhost:8080/rest/path/to/node"
Response:
Status: 502 Bad Gateway
Status:
201 Created
409 Source path doesn't exists
412 Destination path already exists
502 Destination URI isn't a valid resource path
COPY Copy a resource (and its subtree) to a new location
Example:
curl -X COPY -H "Destination: http://localhost:8080/rest/new/path/to/node" "http://localhost:8080/rest/path/to/node"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/new/path/to/node
Status:
201 Created
409 Source path doesn't exists
412 Destination path already exists
502 Destination URI isn't a valid resource path
Binary Content
Request URI: /path/to/some/resource/fcr:content
Methods: GET, PUT, POST
GET Retrieve binary content
Request Headers:
IF-NONE-MATCHIF-MODIFIED-SINCE RANGE
Example (1):
curl "http://localhost:8080/rest/path/to/some/resource/fcr:content"
Response:
Status: 200 OK Headers: ETag: "urn:sha1:cb1a576f22e8e3e110611b616e3e2f5ce9bdb941" Content-Type: image/jpeg Content-Length: 123456 Cache-Control: no-transform, must-revalidate, max-age=0 Last-Modified-At: 2013-01-01T01:23:45Z Link: http://localhost:8080/rest/path/to/some/resource;rel="meta" Accept-Ranges: bytes Body: <binary content>
Example (2):
curl -H "Range: bytes=1-5" "http://localhost:8080/rest/path/to/some/resource/fcr:content"
Response:
Status: 206 Partial Content Headers: ETag: "urn:sha1:cb1a576f22e8e3e110611b616e3e2f5ce9bdb941" Content-Type: image/jpeg Content-Range: bytes 1-5/9106 Content-Length: 5 Cache-Control: Last-Modified-At: 2013-01-01T01:23:45Z Link: http://localhost:8080/rest/path/to/some/resource;rel="meta" Accept-Ranges: bytes Body: <binary content>
Status:
200 OK
206 Partial Content
304 Not Modified
404 Not Found
416 Requested Range Not Satisfiable
POST Upload new binary content
Request Headers:
SLUG (See above)
CONTENT-DISPOSITION The filename provided in the content disposition header will be stored in a premis:hasOriginalName property.
Query Parameters:
CHECKSUM
Example (1):
curl -X POST -d "@image.jpg" "http://localhost:8080/rest/path/to/new/resource/fcr:content" Body: <binary content>
Response (1):
Status: 201 Created Headers: Location: http://localhost:8080/rest/path/to/new/resource/fcr:content
Example (2):
curl -X POST -d "@image.jpg" -H "Content-Disposition: inline; filename=\"image.jpg\"" "http://localhost:8080/rest/path/to/new/resource/fcr:content" Body: <binary content>
Response (2):
Status: 201 Created Headers: Location: http://localhost:8080/rest/path/to/new/resource/fcr:content
Status:
201 Created
409 Checksum Mismatch
PUT Replace existing binary content
Request Headers:
IF-MATCHIF-UNMODIFIED-SINCE
CONTENT-DISPOSITION (see above)
Query Parameters:
CHECKSUM
Example:
curl -X POST -d "@image.jpg" "http://localhost:8080/rest/path/to/some/existing/resource/fcr:content" Body: <binary content>
Response:
Status: 204 No Content
Status:
201 You can also PUT to a new location and Fedora will create the appropriate nodes
204 No Content
409 Checksum Mismatch
412 Precondition Failed
Batch Operations
Request URI: /path/to/some/resource/fcr:batch
Methods: GET, POST, DELETE
GET Retrieve multiple binary resources in a single request
An HTTP method returning multipart/form-data is non-standard and a little unusual, but it seems to work well enough.
Query Parameters:
CHILD Identifier for the children with binary content to retrieve (Optional; if omitted, return all binary content children)
Example:
curl "http://localhost:8080/rest/path/to/some/resource/fcr:batch?child=content&child=thumbnail"
Response:
Status: 200 OK Headers: ETag: "686897696a7c876b7e" Content-Type: multipart/form-data; boundary=AaB03x Content-Length: 123456 Cache-Control: Last-Modified-At: 2013-01-01T01:23:45Z Body: --AaB03x Content-Disposition: attachment; filename="content" Content-Type: image/tiff <binary content> --AaB03x Content-Disposition: attachment; filename="thumbnail" Content-Type: image/jpeg <binary content>
Status:
200
404 If the parent resource doesn't exist, we return a 404.
What if an explicitly provided dsid doesn't exist? Is this a 404 too?
POST Bulk creation, modification and deletion of resources with a single multipart request
This endpoint supports two different content types, multipart/mixed (preferred) or multipart/form-data (see below).
Request Headers:
CONTENT-TYPE multipart/mixed
In multipart/mixed mode, the content-disposition of each part will determine the behavior of that part. The object-to-be-manipulated is given in the name of the part. The supported content-dispositions are:
- inline; creates or modifies an object's properties (either by replacing the properties with the supplied RDF, or by executing a SPARQL-Update query)
- attachment; creates and replaces the binary content of an object
- delete; deletes an object
Example:
# creates (or replaces) three datastreams: # http://localhost:8080/rest/path/to/some/resource/a # http://localhost:8080/rest/path/to/some/resource/b # http://localhost:8080/rest/path/to/some/resource/c curl -X POST -H "Content-Type: multipart/mixed; boundary=----" -d @multipart_request "http://localhost:8080/rest/path/to/some/resource/fcr:batch"
# content of multipart_request ---- Content-Disposition: attachment; name="a"; filename="img002.jpg" Content-Type: image/jpeg <binary content here> ---- Content-Disposition: attachment; name="b"; filename="img003.jpg" Content-Type: image/jpeg <binary content here> ---- Content-Disposition: attachment; name="c"; filename="img002.jpg" Content-Type: image/jpeg <binary content here> ----
Example:
# Creates or modifies properties of two objects: # http://localhost:8080/rest/path/to/some/resource # http://localhost:8080/rest/path/to/some/resource/a curl -X POST -H "Content-Type: multipart/mixed; boundary=----" -d @multipart_request "http://localhost:8080/rest/path/to/some/resource/fcr:batch"
# content of multipart_request ---- Content-Disposition: inline; name="." Content-Type: application/sparql-update INSERT { <> dc:title "abc" } WHERE { } ---- Content-Disposition: inline; name="a" Content-Type: application/rdf+xml <> dc:title "xyz" ----
Response:
Status: 201 Created
Status:
201
POST Bulk creation, modification and deletion of resources with a single multipart request
Request Headers:
CONTENT-TYPE multipart/form-data
For clients unable to produce multipart/mixed requests, a multipart/form-data endpoint is also provided. It uses heuristics to determine which action to apply:
- if the entity has a supplied filename, it will create a new datastream at the part's name
- if the content is RDF or SPARQL-Update (and doesn't have a filename set), add or update triples
- if the entity's name is "delete[]", the content of the body is a relative path to a resource to delete
- otherwise, it will create a new datastream at the part's name using the part's content.
Example:
# creates the ds1 resource curl -X POST -F "ds1=@image.png" "http://localhost:8080/rest/path/to/some/resource/fcr:batch" # execute the supplied SPARQL-Update query against the resource curl -X POST -F ".=@sparql_update_query;type=application/sparql-update" "http://localhost:8080/rest/path/to/some/resource/fcr:batch" # delete the ds1 resource curl -X POST -F "delete[]=ds1" "http://localhost:8080/rest/path/to/some/resource/fcr:batch" # or any combination of the above.
Response:
Status: 201 Created
Status:
201
DELETE Delete multiple resources in a single request
Query Parameters:
CHILD List of child resources to delete
Example:
# removes both old-content and backup-content resources curl -X DELETE "http://localhost:8080/rest/path/to/some/resource/fcr:batch?child=old-content&child=backup-content"
Response:
Status: 204 No Content
Status:
204 No Content
Export / Import
Request URI: /path/to/some/resource
Methods: GET, POST
Objects are exported and imported relative to the request URI path given. E.g., if you run:
curl http://localhost:8080/rest/path/to/resource/fcr:export > export.xml curl -X POST -d @export.xml http://localhost:8080/rest/somewhere/else
The resource will be imported to http://localhost:8080/rest/somewhere/else/resource.
GET fcr:export Retrieve serialized form of a resource and its subtree.
Request Headers:
FORMAT Export formats; the exact formats available depend on the repository configuration.
The available export formats for an object are available as properties of nodes, e.g. this node exports jcr/xml:
<> <http://fedora.info/definitions/v4/rest-api#exportsAs> <./fcr:export?format=jcr/xml> ;
Example:
curl "http://localhost:8080/rest/path/to/some/resource/fcr:export"
Response:
Status: 200 Headers: Content-Type: application/xml Body: <?xml version="1.0" encoding="UTF-8"?><sv:node xmlns:dc="http://purl.org/dc/terms/" xmlns:nt="http://www.jcp.org/jcr/nt/1.0" xmlns:ns001="http://purl.org/dc/elements/1.1/" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:test="info:fedora/test/" xmlns:image="http://www.modeshape.org/images/1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:fedorarelsext="http://fedora.info/definitions/v4/rels-ext#" xmlns:mix="http://www....
Status:
200 OK
404 Not Found
POST fcr:import Import a serialized resource
Request Headers:
FORMAT Import formats. The exact formats available depend on the repository configuration.
Example:
curl -X POST -d "@export.xml" "http://localhost:8080/rest/path/to/some/fcr:import?format=jcr/xml" Body: <?xml version="1.0" encoding="UTF-8"?><sv:node xmlns:dc="http://purl.org/dc/terms/" xmlns:nt="http://www.jcp.org/jcr/nt/1.0" xmlns:ns001="http://purl.org/dc/elements/1.1/" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:test="info:fedora/test/" xmlns:image="http://www.modeshape.org/images/1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:fedorarelsext="http://fedora.info/definitions/v4/rels-ext#" xmlns:mix="http://www....
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/path/to/some/resource/
Status:
201 Created
404 Path not found
Versioning
Request URI: /path/to/some/resource/fcr:versions
Methods: GET, POST
Versioning is not fully implemented in Fedora 4 alpha
GET Get a list of the available versions of an object
GET Get a previous version of an object
POST Tag a new version of the object with a labeled version
Services
Backup and Restore
Request URI: /
Methods: GET, POST
POST fcr:backup Initiate a (consistent) backup of the repository.
The backup will be stored in a temporary directory on the server. As yet, there is not a REST API method for retrieving the content of the backup.
Example:
curl -X POST "http://localhost:8080/rest/fcr:backup"
Response:
Status: 200 OK Body: /tmp/fcrepo4-data/path/to/backup/directory
Status:
200 OK
POST fcr:restore Restore a backup file into the repository
Does this overwrite existing data? Merge data with the backup?
Example:
curl -X POST -d "@backup.xml" "http://localhost:8080/rest/fcr:restore" Body: <binary content>
Response:
Status: 204 No Content
Status:
204
Identifiers
Request URI: /path/to/some/resource/fcr:identifier
Methods: GET, POST
POST Mint 1 or more new identifiers
Request Headers:
ACCEPT text/turtle, text/rdf+n3, application/n3, text/n3, application/rdf+xml, application/json+rdf, application/n-triples, text/html
Query Parameters:
COUNT Number of identifiers to create (Optional; defaults to 1)
Example (1):
curl -X POST "http://localhost:8080/rest/fcr:identifier"
Response:
Status: 200 OK Headers: Content-Type: text/turtle Body: <http://localhost:8080/rest/fcr:identifier> <http://fedora.info/definitions/v4/repository#hasMember> <<http://localhost:8080/rest/newly-minted-identifier>
Example (2):
curl -X POST "http://localhost:8080/rest/fcr:identifier?count=3"
Response:
Status: 200 OK Headers: Content-Type: text/turtle Body: <http://localhost:8080/rest/fcr:identifier> <http://fedora.info/definitions/v4/repository#hasMember> <http://localhost:8080/rest/newly-minted-identifier> , <http://localhost:8080/rest/another-newly-minted-identifier> , <http://localhost:8080/rest/yet-another-minted-identifier>
Example (3):
curl -X POST "http://localhost:8080/rest/path/to/some/resource/fcr:identifier"
Response:
Status: 200 OK Headers: Content-Type: text/turtle Body: <http://localhost:8080/rest/path/to/some/resource/fcr:identifier> <http://fedora.info/definitions/v4/repository#hasMember> <http://localhost:8080/rest/path/to/some/resource/newly-minted-identifier>
Status:
200 OK
Transactions
Request URI: /fcr:tx; /path/to/transaction/fcr:tx
Methods: POST
GET Get the current status of a transaction
TODO?
POST Create a new transaction
After retrieving a transaction resource, the client can execute any REST API method prefixed by the transaction location.
Transactions are automatically closed and rolled back after 3 minutes of inactivity. Transactions can be refreshed by POSTing to /rest/{tx:id}/fcr:tx
Example:
curl -X POST "http://localhost:8080/rest/fcr:tx"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/tx:83e34464-144e-43d9-af13-b3464a1fb9b5 Expires: Sat, 16 Nov 2013 00:32:57 GMT
Usage:
curl -X POST "http://localhost:8080/rest/tx:83e34464-144e-43d9-af13-b3464a1fb9b5/path/to/object/to/create" curl -X DELETE "http://localhost:8080/rest/tx:83e34464-144e-43d9-af13-b3464a1fb9b5/path/to/resource/to/delete" curl -X POST "http://localhost:8080/rest/tx:83e34464-144e-43d9-af13-b3464a1fb9b5/fcr:tx/fcr:commit
Status:
201 Created
POST Save and commit an open transaction.
Any operations you made within the scope of the transaction will be applied together, meaning if any of them fail, the whole transaction will fail.
Example:
curl -X POST "http://localhost:8080/rest/tx:123456789/fcr:tx/fcr:commit"
Response:
Status: 204 No Content
Status:
204 No Content
POST Rollback and close an open transaction
Example:
curl -X POST "http://localhost:8080/rest/tx:123456789/fcr:tx/fcr:rollback"
Response:
Status: 204 No Content
Status:
204 No Content
Fixity
Request URI: /path/to/some/resource/fcr:fixity
Methods: GET
GET Get the fixity report for an object
Checking fixity requires retrieving the content from the binary store and may take some time. In the event of fixity corruption, in some cases, this will be automatically repaired. See Self-healing storage.
Request Headers:
ACCEPT text/turtle, text/rdf+n3, application/n3, text/n3, application/rdf+xml, application/json+rdf, application/n-triples, text/html
Example:
curl -H "Accept: text/turtle" "http://localhost:8080/rest/path/to/some/binary/resource/fcr:fixity"
Response:
Status: 200 OK Headers: Content-Type: text/turtle Body: <http://localhost:8080/rest/path/to/some/binary/resource> a <http://fedora.info/definitions/v4/rest-api#resource> , <http://fedora.info/definitions/v4/rest-api#datastream> ; <http://fedora.info/definitions/v4/repository#hasFixityResult> [ <http://fedora.info/definitions/v4/repository#computedChecksum> <urn:sha1:5441456941dd8b3ee0832b991ee93ba0c0a558f7> ; <http://fedora.info/definitions/v4/repository#computedSize> "471019"^^<http://www.w3.org/2001/XMLSchema#long> ; <http://fedora.info/definitions/v4/repository#hasLocation> </org.infinispan.loaders.file.FileCacheStore:FedoraRepositoryBinaryData:org.infinispan.loaders.file.FileCacheStore:/var/folders/v3/wl82s37145b6jydsh9y5n8l40000gp/T//fcrepo4-data/fcrepo.ispn.binary.CacheDirPath> ; <http://fedora.info/definitions/v4/repository#isFixityResultOf> <http://localhost:8080/rest/path/to/some/binary/resource> ; <http://fedora.info/definitions/v4/repository#status> "SUCCESS" ] .
Status:
200 OK
404 Resource not found
Workspaces
Request URI: /fcr:workspaces/(workspace name)
Methods: POST, DELETE
POST Create a new workspace
Example:
curl -X POST "http://localhost:8080/rest/fcr:workspaces/abc" # create a new workspace called "abc"
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/workspace:abc
Usage:
After creating a workspace, you can execute other REST API methods by prefixing the workspace identifier to requests
curl -X POST "http://localhost:8080/rest/fcr:workspaces/abc" curl -X POST "http://localhost:8080/rest/workspace:abc/path/to/some/new/resource
Status:
201 Created
DELETE Delete a new workspace
Example:
curl -X DELETE "http://localhost:8080/rest/fcr:workspaces/abc" # delete a new workspace called "abc"
Response:
Status: 204 No Content
Status:
204 No Content
Content Modeling
Request URI: /fcr:nodetypes
Methods: GET, POST
Node types
GET get a list of registered types (as RDFS triples)
Request Headers:
ACCEPT text/turtle, text/rdf+n3, application/n3, text/n3, application/rdf+xml, application/json+rdf, application/n-triples, text/html
Example:
curl "http://localhost:8080/rest/fcr:nodetypes"
Response:
Status: 200 OK Headers: Content-Type: text/turtle Body: <http://fedora.info/definitions/v4/rest-api#object> a <http://www.w3.org/2000/01/rdf-schema#Class> ; <http://www.w3.org/2000/01/rdf-schema#label> "fedora:object" ; <http://www.w3.org/2000/01/rdf-schema#subClassOf> <http://fedora.info/definitions/v4/rest-api#resource> . <http://fedora.info/definitions/v4/rest-api#resource> a <http://www.w3.org/2000/01/rdf-schema#Class> ; <http://www.w3.org/2000/01/rdf-schema#label> "fedora:resource" ; <http://www.w3.org/2000/01/rdf-schema#subClassOf> <http://fedora.info/definitions/v4/rest-api#relations> , <http://www.jcp.org/jcr/mix/1.0created> , <http://www.jcp.org/jcr/mix/1.0lastModified> , <http://www.jcp.org/jcr/mix/1.0lockable> , <http://www.jcp.org/jcr/mix/1.0versionable> . [...]
Status:
200 OK
POST Update the list of node types
The request body format for updating nodetypes is JCR's CND syntax.
Example:
curl -X POST -H "Content-Type: text/cnd" -d "@cnd.txt" "http://localhost:8080/rest/fcr:nodetypes" Body: [fedora:custom_node_type] > fedora:resource mixin - fedora:thumbnail (string)
Response:
Status: 204 No Content
Status:
204 No Content
Namespaces
Request URI: /fcr:namespaces
Methods: GET, POST
GET get a list of registered namespaces and default prefixes
Request Headers:
ACCEPT text/turtle, text/rdf+n3, application/n3, text/n3, application/rdf+xml, application/json+rdf, application/n-triples, text/html
Example:
curl "http://localhost:8080/rest/fcr:namespaces"
Response:
Status: 200 OK Headers: Content-Type: text/turtle Body: @prefix dc: <http://purl.org/dc/terms/> . @prefix nt: <http://www.jcp.org/jcr/nt/1.0> . @prefix fcrepo: <http://fedora.info/definitions/v4/repository#> . dc: a <http://purl.org/vocommons/voaf#Vocabulary> ; <http://purl.org/vocab/vann/preferredNamespacePrefix> "dc" ; <http://purl.org/vocab/vann/preferredNamespaceUri> "http://purl.org/dc/terms/" . fcrepo: a <http://purl.org/vocommons/voaf#Vocabulary> ; <http://purl.org/vocab/vann/preferredNamespacePrefix> "fcrepo" ; <http://purl.org/vocab/vann/preferredNamespaceUri> "http://www.jcp.org/jcr/1.0" . nt: a <http://purl.org/vocommons/voaf#Vocabulary> ; <http://purl.org/vocab/vann/preferredNamespacePrefix> "nt" ; <http://purl.org/vocab/vann/preferredNamespaceUri> "http://www.jcp.org/jcr/nt/1.0" . [....]
Status:
200 Ok
POST add, modify, or delete namespaces
There are some restrictions on what can be modified. For example, several foundation namespaces cannot be deleted:
- fcrepo (http://fedora.info/definitions/v4/repository#)
- mix (http://www.jcp.org/jcr/mix/1.0)
- mode (http://www.modeshape.org/1.0)
- nt (http://www.jcp.org/jcr/nt/1.0)
- sv (http://www.jcp.org/jcr/sv/1.0)
- xml (http://www.w3.org/XML/1998/namespace)
- xmlns (http://www.w3.org/2000/xmlns/)
- xs (http://www.w3.org/2001/XMLSchema)
- xsi (http://www.w3.org/2001/XMLSchema-instance)
Additionally, deleting namespaces such as fedora (http://fedora.info/definitions/v4/rest-api#) and premis (http://www.loc.gov/premis/rdf/v1#) can render your repository unusable.
Example:
curl -X POST -H "Content-Type: application/sparql-update" -d "@namespaces.rdf" "http://localhost:8080/rest/fcr:namespaces" Body: # Register the namespace 'info:some-namespace' with the prefix 'some' INSERT { <info:some-namespace> <http://purl.org/vocab/vann/preferredNamespacePrefix> "some" } WHERE { }
Response:
Status: 204 No Content
Status:
204
Sitemaps
Request URI: /sitemap
Methods: GET, POST
GET get an XML Sitemap of content in the repository
Example (1):
curl "http://localhost:8080/rest/sitemap"
Response:
Status: 200 OK Headers: Content-Type: text/xml Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?><sitemap:sitemapindex xmlns:sitemap="http://www.sitemaps.org/schemas/sitemap/0.9"><sitemap:sitemap><sitemap:loc>http://localhost:8080/rest/sitemap/1</sitemap:loc><sitemap:lastmod>2013-11-15T16:51:38.132-08:00</sitemap:lastmod><sitemap:changefreq>monthly</sitemap:changefreq><sitemap:priority>0.8</sitemap:priority></sitemap:sitemap></sitemap:sitemapindex>
Example (2):
curl "http://localhost:8080/rest/sitemap/1"
Response:
Status: 200 OK Headers: Content-Type: text/xml Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?><sitemap:urlset xmlns:sitemap="http://www.sitemaps.org/schemas/sitemap/0.9"><sitemap:url><sitemap:loc>http://localhost:8080/rest/00/cf/42/b8/00cf42b8-3a11-4af0-8972-48be8d9db5cd</sitemap:loc><sitemap:lastmod>2013-11-15T16:52:32.418-08:00</sitemap:lastmod><sitemap:changefreq>monthly</sitemap:changefreq><sitemap:priority>0.8</sitemap:priority></sitemap:url></sitemap:urlset>
Status:
200 OK
Search
Properties text
Request URI: /fcr:search
Methods: GET
GET HTML form for submitting SPARQL queries
Request Headers:
ACCEPT text/html
GET execute a fulltext search over indexed properties in the repository
Query Parameters:
Q Query term
OFFSET Pagination control for member resources
LIMIT Pagination control for member resources
Request Headers:
ACCEPT text/turtle, text/rdf+n3, application/n3, text/n3, application/rdf+xml, application/json+rdf, application/n-triples, text/html
Example:
curl -H "Accept: text/turtle" "http://localhost:8080/rest/fcr:search?q=bypassAdmin"
Response:
Status: 200 Headers: Link: http://localhost:8080/rest/fcr:search?q=bypassAdmin&offset=0&limit=25;rel="first" Content-Type: text/turtle Body: <http://localhost:8080/rest/fcr:search?q=bypassAdmin> a <http://www.w3.org/ns/ldp#Page> , <http://sindice.com/vocab/search#Page> ; <http://fedora.info/definitions/v4/repository#hasMember> <http://localhost:8080/rest/00/cf/42/b8/00cf42b8-3a11-4af0-8972-48be8d9db5cd> ; <http://fedora.info/definitions/v4/rest-api#hasMoreResults> false ; <http://sindice.com/vocab/search#itemsPerPage> "25"^^<http://www.w3.org/2001/XMLSchema#int> ; <http://sindice.com/vocab/search#searchTerms> "bypassAdmin" ; <http://sindice.com/vocab/search#startIndex> "0"^^<http://www.w3.org/2001/XMLSchema#long> ; <http://sindice.com/vocab/search#totalResults> "1"^^<http://www.w3.org/2001/XMLSchema#long> ; <http://www.w3.org/ns/ldp#firstPage> <http://localhost:8080/rest/fcr:search?q=bypassAdmin&offset=0&limit=25> ; <http://www.w3.org/ns/ldp#nextPage> () ; <http://www.w3.org/ns/ldp#pageOf> <http://localhost:8080/rest/fcr:search?q=bypassAdmin> . <http://localhost:8080/rest/00/cf/42/b8/00cf42b8-3a11-4af0-8972-48be8d9db5cd> a <http://fedora.info/definitions/v4/rest-api#object> , <http://fedora.info/definitions/v4/rest-api#resource> ; <http://fedora.info/definitions/v4/repository#created> "2013-11-16T00:52:32.432Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ; <http://fedora.info/definitions/v4/repository#createdBy> "bypassAdmin"^^<http://www.w3.org/2001/XMLSchema#string> ; <http://fedora.info/definitions/v4/repository#lastModified> "2013-11-16T00:52:32.418Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ; <http://fedora.info/definitions/v4/repository#lastModifiedBy> "bypassAdmin"^^<http://www.w3.org/2001/XMLSchema#string> ; <http://fedora.info/definitions/v4/repository#uuid> "b9fb7c68-c5c8-4ecd-a1b6-5ffeeeb2ba3d"^^<http://www.w3.org/2001/XMLSchema#string> ;
Status:
200 OK
400 Bad Request
SPARQL
Request URI: /fcr:sparql
Methods: GET
SPARQL query functionality is experimental and is not yet in any fcrepo4 release.
GET HTML form for submitting SPARQL queries
Request Headers:
ACCEPT text/html
POST execute a query using a subset of SPARQL
Example:
curl -H "Content-Type: application/sparql-query" -d @sparqlQuery.txt -H "Accept: " "http://localhost:8080/rest/fcr:sparql" Body: SELECT ?subject FROM <> WHERE { ?subject dc:title ?title }
Response:
Status: 200 Headers: Content-Type: text/turtle Body:
Status:
200 OK
400 Bad Request
Transform
Request URI: /fcr:transform/{program}
Methods: GET, POST
GET get a resource transformed with the default transform
Request Headers:
Example:
@prefix fcrepo : <http://fedora.info/definitions/v4/repository#> id = . :: xsd:string ; title = dc:title :: xsd:string; uuid = fcrepo:uuid :: xsd:string ;
curl http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f/fcr:transform/default
Response:
Status: 200 OK Headers: Content-Type: application/json Transfer-Encoding: chunked Server: Jetty(8.1.11.v20130520) Body: [{"id":["http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f"],"title":[],"uuid":["07630a24-5a0b-4ba7-80ab-0691f68667ce"]}]
Status:
200 OK
400 Bad Request
POST get a resource transformed with the supplied transform
Output formats: application/json,text/tab-separated-values,text/csv,text/sse,text/plain,application/sparql-results+json,application/sparql-results+xml,application/sparql-results+bio,text/turtle,text/rdf+n3,application/N-triples,application/rdf_xml
Example:
curl -X POST -H "Content-Type: application/rdf+ldpath" -d "@post.txt" "http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f/fcr:transform" Body: @prefix fcrepo : <http://fedora.info/definitions/v4/repository#> id = . :: xsd:string ; title = dc:title :: xsd:string; uuid = fcrepo:uuid :: xsd:string ;
Response:
Status: 200 OK Headers: Content-Type: application/json Transfer-Encoding: chunked Server: Jetty(8.1.11.v20130520) Body: [{"id":["http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f"],"title":[],"uuid":["07630a24-5a0b-4ba7-80ab-0691f68667ce"]}]
Status:
200 OK
400 Bad Request
Access Roles
Request URI: /path/to/some/resource/fcr:accessroles
Methods: GET, POST, DELETE
Arbitrary access roles may be set through this API. However, they are only enforced when paired with a Policy Enforcement Point that is aware of access roles.
GET Get a list of all the roles assigned to principals on this resource
Output formats: application/json
Query Parameters:
EFFECTIVE When supplied, gets the list of effective roles for this resource, including those inherited from the parent
Example:
curl "http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f/fcr:accessroles"
Response:
Status: 200 OK Headers: Content-Type: application/json Transfer-Encoding: chunked Server: Jetty(8.1.11.v20130520) Body: {"principal name 3":["admin"],"principal name 1":["reader"],"principal name 2":["writer"]}
Status:
200 OK
204 No Content
POST Set the roles assigned on this resource
Example:
curl -X POST -H "Content-Type: application/json" -d "@post.txt" "http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f/fcr:accessroles" Body: { "principal name 1" : [ "reader" ], "principal name 2" : [ "writer" ], "principal name 3" : [ "admin" ] }
Response:
Status: 201 Created Headers: Location: http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f/fcr:accessroles Content-Length: 0 Server: Jetty(8.1.11.v20130520)
Status:
201 Created
400 Bad Request
DELETE Clear all roles assignments from this resource
Example:
curl -X DELETE "http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f/fcr:accessroles"
Response:
Status: 204 No Content Headers: Server: Jetty(8.1.11.v20130520)
Status:
204 No Content