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. (TODO: 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 (link me!)

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 or modify namespaces

There are some restrictions on what can be modified. (TODO: what are the caveats?)

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:

default transform

@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

Page tree

RESTful HTTP API

Overview

Introduction

Changes planned

Endpoints

Resources

Objects

Binary Content

Batch Operations

Export / Import

Versioning

Services

Backup and Restore

Identifiers

Transactions

Fixity

Workspaces

Content Modeling

Node types

Namespaces

Sitemaps

Search

Properties text

SPARQL

Transform

Access Roles