CSS Stylesheet |
---|
h3 { background-color: #eee; padding: 0.6em; } #content .code { margin-left: 2.5em!important; background-color: #fafafa!important; } .pdl .syntaxhighlighter table td.code .container, .syntaxhighlighter .line.alt2, .syntaxhighlighter .line.alt1 { background-color: #fafafa!important; } |
Table of Contents
Expand | |
---|---|
|
Overview
Introduction
Excerpt |
---|
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)ld+json
- application/n-quadsapplication/n-triples
- application/rdf+jsonapplicationxml
- text/n3 (or text/rdf+xmln3)
- text/trigplain
- text/turtle (or application/x-turtle)
The text/html response also includes embedded RDFa markup.
The API is based loosely around the Fedora 4 implements 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 Containers ("fedora:objectContainer"), containing RDF properties and 0 or more child nodesresources
- Binaries, containing any binary payload (roughly corresponding to Fedora 3 datastreams)
...
Containers
excerpt-include | ||||
---|---|---|---|---|
|
Binary Content
...
Batch Operations
...
Export / Import
...
Versioning
...
Services
Backup and Restore
Request URI: /
Methods: GET, POST
...
Info |
---|
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:
Code Block |
---|
curl -X POST "http://localhost:8080/rest/fcr:backup" |
Response:
Code Block |
---|
Status: 200 OK
Body:
/tmp/fcrepo4-data/path/to/backup/directory |
Status:
Status | ||||||
---|---|---|---|---|---|---|
|
...
Example:
Code Block |
---|
curl -X POST -d "@backup.txt" "http://localhost:8080/rest/fcr:restore"
Body:
/tmp/fcrepo4-data/path/to/backup/directory |
Response:
Code Block |
---|
Status: 204 No Content |
Status:
...
Status | ||||||
---|---|---|---|---|---|---|
|
Identifiers
Request URI: /path/to/some/resource/fcr:identifier
Methods: GET, POST
...
Request Headers:
Status | ||||
---|---|---|---|---|
|
Query Parameters:
...
Example (1):
Code Block |
---|
curl -X POST "http://localhost:8080/rest/fcr:identifier" |
Response:
Code Block |
---|
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):
Code Block |
---|
curl -X POST "http://localhost:8080/rest/fcr:identifier?count=3" |
Response:
Code Block |
---|
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):
Code Block |
---|
curl -X POST "http://localhost:8080/rest/path/to/some/resource/fcr:identifier" |
Response:
Code Block |
---|
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:
...
Transactions
Request URI: /fcr:tx; /path/to/transaction/fcr:tx
Methods: POST
Get the current status of the repository in a transaction Status title GET
Example:
Code Block |
---|
curl "http://localhost:8080/rest/tx:86dd0891-d975-42d8-8837-a24ad6041b59" |
Response:
Code Block |
---|
Status: 200 OK
Headers:
Link: http://localhost:8080/rest/tx:86dd0891-d975-42d8-8837-a24ad6041b59?limit=-1&offset=0;rel="first"
Body:
Same as non-transaction response. |
Status:
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
...
Info |
---|
After retrieving a transaction resource, the client can execute any REST API method prefixed by the transaction location. |
Warning |
---|
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:
Code Block |
---|
curl -X POST "http://localhost:8080/rest/fcr:tx" |
Response:
Code Block |
---|
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:
Code Block |
---|
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:
Status | ||||||
---|---|---|---|---|---|---|
|
...
|
Export and Import
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
Versioning
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
Services
Access Roles
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
Backup and Restore
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
Fixity
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
Node Types
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
Transactions
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
Transform
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
Example:
Code Block |
---|
curl -X POST "http://localhost:8080/rest/tx:123456789/fcr:tx/fcr:commit" |
Response:
Code Block |
---|
Status: 204 No Content |
Status:
...
...
Example:
Code Block |
---|
curl -X POST "http://localhost:8080/rest/tx:123456789/fcr:tx/fcr:rollback" |
Response:
Code Block |
---|
Status: 204 No Content |
Status:
...
Fixity
Request URI: /path/to/some/resource/fcr:fixity
Methods: GET
Get the fixity report for an object Status title GET
Note |
---|
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:
Status | ||||
---|---|---|---|---|
|
Example:
Code Block |
---|
curl -H "Accept: text/turtle" "http://localhost:8080/rest/path/to/some/binary/resource/fcr:fixity" |
Response:
Code Block |
---|
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:
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
Workspaces
Request URI: /fcr:workspaces/(workspace name)
Methods: POST, DELETE
...
Example:
Code Block |
---|
curl -X POST "http://localhost:8080/rest/fcr:workspaces/abc" # create a new workspace called "abc" |
Response:
Code Block |
---|
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
Code Block |
---|
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:
...
...
Example:
Code Block |
---|
curl -X DELETE "http://localhost:8080/rest/fcr:workspaces/abc" # delete a new workspace called "abc" |
Response:
Code Block |
---|
Status: 204 No Content |
Status:
...
Content Modeling
Request URI: /fcr:nodetypes
Methods: GET, POST
Node types
get a list of registered types (as RDFS triples) Status title GET
Request Headers:
Status | ||||
---|---|---|---|---|
|
Example:
Code Block |
---|
curl "http://localhost:8080/rest/fcr:nodetypes" |
Response:
Code Block |
---|
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:
Status | ||||||
---|---|---|---|---|---|---|
|
...
Info |
---|
The request body format for updating nodetypes is JCR's CND syntax. |
Example:
Code Block |
---|
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:
Code Block |
---|
Status: 204 No Content |
Status:
...
Namespaces
Request URI: /fcr:namespaces
Methods: GET, POST
get a list of registered namespaces and default prefixes Status title GET
Request Headers:
Status | ||||
---|---|---|---|---|
|
Example:
Code Block |
---|
curl "http://localhost:8080/rest/fcr:namespaces" |
Response:
Code Block |
---|
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:
Status | ||||||
---|---|---|---|---|---|---|
|
...
Info |
---|
There are some restrictions on what can be modified. For example, several foundation namespaces cannot be deleted:
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:
Code Block |
---|
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:
Code Block |
---|
Status: 204 No Content |
Status:
...
Search
Properties text
Request URI: /fcr:search
Methods: GET
HTML form for submitting SPARQL queries Status title GET
Request Headers:
Status | ||||
---|---|---|---|---|
|
execute a fulltext search over indexed properties in the repository Status title GET
Query Parameters:
...
Status | ||||
---|---|---|---|---|
|
Status | ||||
---|---|---|---|---|
|
Request Headers:
Status | ||||
---|---|---|---|---|
|
Example:
Code Block |
---|
curl -H "Accept: text/turtle" "http://localhost:8080/rest/fcr:search?q=bypassAdmin" |
Response:
Code Block |
---|
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:
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
SPARQL
Request URI: /fcr:sparql
Methods: GET, POST
...
Request Headers:
Status | ||||
---|---|---|---|---|
|
...
Request Headers:
Status | ||||
---|---|---|---|---|
|
Example (1):
Code Block |
---|
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):
Code Block | ||
---|---|---|
| ||
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):
Code Block |
---|
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):
Code Block |
---|
Status: 200
Headers:
Content-Type: text/turtle
Body:
|
Status:
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
Transform
Request URI: /fcr:transform/{program}
Methods: GET, POST
Status | ||
---|---|---|
|
Request Headers:
Example:
Code Block | ||
---|---|---|
| ||
@prefix fcrepo : <http://fedora.info/definitions/v4/repository#>
id = . :: xsd:string ;
title = dc:title :: xsd:string;
uuid = fcrepo:uuid :: xsd:string ; |
Code Block |
---|
curl http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f/fcr:transform/default |
Response:
Code Block |
---|
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:
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
...
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:
Code Block |
---|
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:
Code Block |
---|
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:
Status | ||||||
---|---|---|---|---|---|---|
|
Status | ||||||
---|---|---|---|---|---|---|
|
Access Roles
Request URI: /path/to/some/resource/fcr:accessroles
Methods: GET, POST, DELETE
Warning |
---|
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 a list of all the roles assigned to principals on this resource Status title GET
Output formats: application/json
Query Parameters:
Status | ||||
---|---|---|---|---|
|
Example:
Code Block |
---|
curl "http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f/fcr:accessroles"
|
Response:
Code Block |
---|
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:
...
...
Request Headers:
...
Example:
Code Block |
---|
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:
Code Block |
---|
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:
...
Status | ||||||
---|---|---|---|---|---|---|
|
...
Example:
Code Block |
---|
curl -X DELETE "http://localhost:8080/rest/49/3d/24/41/493d2441-0541-41c7-a23b-09d1f17d4a0f/fcr:accessroles"
|
Response:
Code Block |
---|
Status: 204 No Content
Headers:
Server: Jetty(8.1.11.v20130520)
|
Status:
...
Sitemaps
Include Page | ||
---|---|---|
|