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

Unable to render {include} The included page could not be found.

Binary Content

Unable to render {include} The included page could not be found.

Batch Operations

Unable to render {include} The included page could not be found.

Export / Import

Unable to render {include} The included page could not be found.

Versioning

Unable to render {include} The included page could not be found.

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 Replace repository content with data from a backup directory

Example:

curl -X POST -d "@backup.txt" "http://localhost:8080/rest/fcr:restore"
 
Body:
/tmp/fcrepo4-data/path/to/backup/directory

Response:

Status: 204 No Content

Status:

204 Backup restored

500 Error restoring backup

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 the repository in a transaction

Example:

curl "http://localhost:8080/rest/tx:86dd0891-d975-42d8-8837-a24ad6041b59"

Response:

Status: 200 OK

Headers:
Link: http://localhost:8080/rest/tx:86dd0891-d975-42d8-8837-a24ad6041b59?limit=-1&amp;offset=0;rel="first"

Body:
Same as non-transaction response.

Status:

200 OK

410 Transaction not found

POST Create a new transaction (or keep an existing transaction alive)

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

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, POST

GET HTML form for submitting SPARQL queries

Request Headers:

ACCEPT text/html

POST execute a query using a subset of SPARQL

Request Headers:

ACCEPT 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 (1):

curl -X POST -H "Accept:text/csv" -H "Content-Type:application/sparql-query" -d "@sparql-query.txt" http://localhost:8080/rest/fcr:sparql

Body:
SELECT ?x ?uuid
WHERE { ?x <http://fedora.info/definitions/v4/repository#uuid> ?uuid }

Response (1):

Status: 200

Headers:
Content-Type: text/tab-separated-values

Body:
?x
<http://localhost:8080/rest/07/e4/22/ef/07e422ef-8561-4300-91a4-fff4086c8be0>
<http://localhost:8080/rest/f3/e2/41/f8/f3e241f8-b0b0-4274-95e7-4d58a7af9dca>

Example (2):

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 (2):

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

Request Headers:

CONTENT-TYPE application/json

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

Sitemaps

Unable to render {include} The included page could not be found.

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

Search

Properties text

SPARQL

Transform

Access Roles

Sitemaps