Introduction

This document provides a high-level mapping guide between the Fedora 3.x REST API and the Fedora 6.x REST API. See the REST documentation for each version for more details on the parameters each API method supports.

The distinction between an object and a datastream no longer applies in Fedora 6;  everything in Fedora6 is a resource.  Fedora 6 supports two resource types, containers and binaries, which approximate the Fedora3 object and datastream entities.  There are some slight differences in Fedora 6 to how containers and binaries are retrieved and managed;  those differences are spelled out below, where applicable.

Note that Fedora 6 is based on the Linked Data Platform specification, which makes extensive use of the Prefer: header with omit and include attributes to filter linked data results.

Fedora 6 also allows you to place resources in archival groups, which only changes the way data is stored in the OCFL repository -- it does not affect the way data is organized and managed in Fedora 6.

This guide is not intended to be complete;  the Fedora 6 LDP model differs significantly in its details from the Fedora 3 object-with-datastream model, and makes much more extensive use of linked data and HTTP request headers.  Query parameters and request headers that modify or filter default responses are not included in this document.


API Mapping

Fedora 3 API-A Methods


describeRepository

Describe the repository characteristics: URL, version, namespace, admin emails, etc.

Fedora 3: GET /fedora/describe

Fedora 6: GET /rest

The Fedora 3/Fedora 6 endpoints return different information, neither returns anything entirely comprehensive or useful;  this API is mainly useful for verifying that the repository is running.


findObjects

Simple search API to return object PIDs

Fedora 3: GET /fedora/objects?[terms|query]...

Fedora 6:  GET /rest/fcr:search?[condition|fields]...

Fedora 6 provides a simple search endpoint at fcr:search.  More advanced search and discovery is provided by third-party plugins, such as Solr or a graph database.  See fcrepo-camel-toolbox.


getDatastreamDissemination

Get the content of a datastream

Fedora 3: GET /fedora/objects/{pid}/datastreams/{dsID}/content

Fedora 6: GET /rest/path/to/some/resource

To retrieve arbitrary binary resource content  in Fedora 6, do not set the Accept: header.


getDissemination

Get the dissemination implemented by a disseminator method on an object

Fedora 3: GET /fedora/objects/{pid}/methods/{sdefPid}/{method}

Fedora 6:  Not implemented

Fedora 6 does not support Fedora 3 disseminators.


getObjectHistory

Get a list of the dates when the object was created/modified

Fedora 3: GET /fedora/objects/{pid}/versions

Fedora 6: Accept: text/turtle

   Prefer: return=representation;

   omit="http://www.w3.org/ns/ldp#PreferMinimalContainer";

   include="http://www.w3.org/ns/ldp#PreferContainment"

   GET /rest/path/to/resource/fcr:versions

Fedora 6 individual versions are resources contained within the fcr:versions container.


getObjectProfile

Get metadata about the objects

Fedora 3: GET /fedora/objects/{pid}

Fedora 6: Accept: text/turtle

   GET /rest/path/to/resource

The Fedora 6 call applies to container resources. See the Fedora 6 API documentation for the list of accepted Accept: headers for serializing the container resource metadata.


listMethods

List the disseminator methods available on an object

Fedora 3: GET /fedora/objects/{pid}/methods

Fedora 6:  Not implemented

Fedora 6 does not support Fedora 3 disseminators.


resumeFindObjects

Resume simple search to return object PIDs (see findObjects)

Fedora 3: GET /fedora/objects?[sessionToken]&[terms|query]...

Fedora 6: GET /rest/fcr:search?maxResults={maxnum}&offset={page}&[condition|fields]...

The Fedora 6 simple search maxResults and offset query parameters allow you to specify the number of results per page and which result to start with.  See findObjects.

Fedora API-M Methods

addDatastream

Add a datastream to an object

Fedora 3: PUT /fedora/objects/{pid}/{dsID}

Fedora 6: Content-type: <some/mimetype>

   PUT /rest/path/to/resource

   <request body contains the bitstream itself>

To PUT a binary resource:  specify the mime type of the binary resource in the Content-type: request header, and send the bitstream itself in the body of the request.

To have resources saved as archival groups (which maps closely to the Fedora 3 object-with-datastreams structure), include an #ArchivalGroup Link: header in the request.  You can also send the object contents in the body of the request, or set a non-RDF mime type Content-type: header and no body to create a new object with empty content.


addRelationship

Add a RELS-EXT relationship to an object

Fedora 3: POST /fedora/objects/{pid}/relationships/new

Fedora 6: Content-type: text/turtle

   PUT /rest/path/to/resource

Or 

       PATCH /rest/path/to/resource

   Content-Type: application/sparql-update

This Fedora 6 API applies to container or binary description objects. If the MIME type corresponds to a supported RDF format or SPARQL-Update, the Fedora 6 uploaded content will be parsed as RDF or a SPARQL statement  and used to populate the child node properties.


compareDatastreamChecksum

Verify the recorded checksum in Fedora against the file on disk

Fedora 3: GET /fedora/objects/{pid}/datastreams/{dsID}?validateChecksum=true

Fedora 6: GET /path/to/some/resource/fcr:fixity

Note that you must examine the Fedora 6 response body to determine if the checksum verification is successful or not.


export

Export an object to a serialized portable format

Fedora 3: GET /fedora/objects/{pid}/export

Fedora 6: Not implemented

Available for Fedora 6 as a separate tool:  https://github.com/fcrepo-exts/fcrepo-import-export.


getDatastream

Get datastream metadata

Fedora 3: GET /fedora/objects/{pid}/datastreams/{dsID}

Fedora 6: Accept: text/turtle

      GET /rest/path/to/resource

Fedora 6 API call is same as getObjectProfile, as the Fedora 6 API treats everything as a resource.


getDatastreamHistory

Get datastream metadata for every version

Fedora 3: GET /fedora/objects/{pid}/datastreams/{dsid}/history

Fedora 6: Accept: text/turtle

   GET /rest/path/to/resource/fcr:versions

then

    Accept: text/turtle

    GET /rest/path/to/resource/fcr:versions/{versionID}

Retrieving all the metadata for all the versions of a resource in Fedora 6 is a two-step process:  first, retrieve a list of all the versions of a given resource, then go through the list and retrieve the metadata for each version.  The list will be in the body of the fcr:versions response, as objects of the relation ldp:contains.


getDatastreams

Get a list of datastreams in an object

Fedora 3: GET /fedora/objects/{pid}/datastreams

Fedora 6: Accept: text/turtle

      Prefer: return=representation;

   omit="http://www.w3.org/ns/ldp#PreferMinimalContainer";

   include="http://www.w3.org/ns/ldp#PreferContainment"

   GET /rest/path/to/resource

In Fedora 6 a binary resource (datastream) is simply a resource that (usually, but not necessarily) is a child of a container (object) resource.  Filter on <ldp:contains>.


getNextPID

Get a list of the next set of PIDs Fedora will generate

Fedora 3: GET /fedora/objects/nextPID

Fedora 6: Not implemented

Fedora 6 will assign a UUID to a resource upon creation with POST, unless you send a Slug: request header with the ID of the resource in the POST request.


getObjectXML

Get the Fedora 3 internal FOXML representation of an object and its metadata (not the same as export)

Fedora 3: GET /fedora/objects/{pid}/objectXML

Fedora 6: Not implemented

Fedora 6 object properties can be returned as RDF/xml.  See getObjectProfile;  use the Accept: application/rdf+xml header.


getRelationships

Get the RELS-EXT relationships for an object

Fedora 3: GET /fedora/objects/{pid}/relationships

Fedora 6: Accept: application/rdf+xml

   GET /rest/path/to/resource

This Fedora 6 API call applies to container objects.  All resource properties in Fedora 6 are expressed as triple relationships.  Add the Prefer: return=minimal header to get just the properties of the specified resource as well as the links to the other resources it links to (outbound references).  In order to also get the the links to resources that point to the specified resource (inbound references), use the request header Prefer: return=representation;include=”http://fedora.info/definitions/fcrepo#PreferInboundReferences”.


ingest

Add an object to to the Fedora repository

Fedora 3: POST /fedora/objects/{pid}

Fedora 6: PUT /rest/path/to/resource

See the notes on addDatastream.


modifyDatastream

Change a datastream contents and/or metadata

Fedora 3: PUT /fedora/objects/{pid}/datastreams/{dsID}

Fedora 6: 

Metadata: 

PUT /rest/path/to/resource/fcr:metadata

or

PATCH /rest/path/to/resource/fcr:metadata

Content-Type: application/sparql-update

Binary bitstream:

Content-type: <some/mimetype>

PUT /rest/path/to/resource

<request body contains the bitstream itself>


The resource properties can be modified by PUTting the fcr:metadata properties in a request with a RDF format Content-type: header or a PATCH request with a SPARQL-Update body.  Binary content can be sent in the body of the request with the appropriate resource mime type set in the Content-type: header to update the resource’s contents.  Note that a new resource (RDF or binary) will be created if the resource endpoint does not exist (identical to ingest/addDatastream).


modifyObject

Change an object’s metadata

Fedora 3: PUT /fedora/objects/{pid}

Fedora 6: Content-Type: text/turtle 

   Prefer: handling=lenient

   PUT /rest/path/to/resource

   <body contains turtle RDF with updated properties>

or

   PATCH /rest/path/to/resource

   Content-Type: application/sparql-update

This Fedora 6 API call applies to container objects.  The resource properties can be modified by PUTting the properties in a request to the container resource endpoint with a RDF format Content-type: header or a PATCH request with a SPARQL-Update body.


purgeDatastream

Delete a datastream from an object

Fedora 3: DELETE /fedora/objects/{pid}/datastreams/{dsID}

Fedora 6: DELETE /rest/path/to/resource

   DELETE /rest/path/to/resource/fcr:tombstone

Resources that have been deleted in Fedora 6 are replaced with tombstone markers;  to reuse the resource ID, you must also DELETE the tombstone.


purgeObject

Delete an object and all its datastreams.

Fedora 3: DELETE /fedora/objects/{pid}

Fedora 6: DELETE /rest/path/to/resource

   DELETE /rest/path/to/resource/fcr:tombstone

See the notes for purgeDatastream.  Note that any child resources under the deleted resource will also be deleted (and replaced by tombstones).


purgeRelationship

Delete a Fedora 3 RELS-EXT relationship

Fedora 3: DELETE /fedora/objects/{pid}/relationships

Fedora 6: Content-Type: text/turtle 

   Prefer: handling=lenient

   <body contains turtle RDF with updated properties>

   PUT /rest/path/to/resource

Or

   Content-Type: application/sparql-update

   PATCH /rest/path/to/resource

This Fedora 6 API call applies to container objects. Note that deleting properties in Fedora 6 works as a variation of the modify* API calls.  The RDF body in the first instance should contain all the properties except the ones you want to delete;  in the second case, the use a SPARQL delete statement.


setDatastreamState

Fedora 3: PUT /objects/{pid}/datastreams/{dsID} ? [dsState]

Fedora 6: Content-Type: text/turtle 

   Prefer: handling=lenient

   <body contains turtle RDF with updated http://fedora.info/definitions/1/0/access/objState property >

   PUT /rest/path/to/resource/fcr:metadata

Or

   Content-Type: application/sparql-update

   PATCH /rest/path/to/resource/fcr:metadata

Note that modifying resource properties in Fedora 6 also works as a variation of the modify* API calls.  The RDF body in the first instance should contain all the properties, including the updated ones;  in the second case, the use a SPARQL update statement.

The objState relation is http://fedora.info/definitions/1/0/access/objState.


setDatastreamVersionable

Set versioning on a datastream

Fedora 3: PUT /fedora/objects/{pid}/datastreams/{dsID} ? [true|false]

Fedora 6: Not implemented

Fedora 6 can be configured to automatically version all resources with every update, or require that the versions for all resources be manually managed.  Currently per-resource versioning policies are not supported.  See the Auto-versioning documentation for more information.


validate

Fedora 3: GET /objects/{pid}/validate

Fedora 6: Not implemented

Given the flexibility of how data can be modelled in Fedora 6, there does not exist any validation tool that can accommodate all data modelling scenarios, or the formats of all possible binary resources (including XML).  See the OCFL validator tool to validate your underlying OCFL repository.



All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.