Preservica Entity REST API

Please note: for v6 onwards, please visit https://demo.preservica.com/api/entity/documentation.html for updated Swagger documentation on the Entity API.

The Entity API documented below relates to previous versions.

Requesting Data through the REST API

The REST API is accessed over HTTP or HTTPS through the normal server URL. Requests should include a valid Preservica access token (see Chapter 6) in a Preservica-Access-Token HTTP header. Data returned from any method on the API will be based on the access permissions of the user for whom the access token was generated.

For backward compatibility reasons, the REST API also supports sending requests with a basic HTTP authentication in an Authorization header.

Forming the URL

Preservica Native Identifiers

Each resource stored in Preservica is uniquely addressable through a reference (a UUID), which is assigned to it on creation. Further, each resource is assigned a data-type, e.g. Collection, Deliverable Unit, File. These two pieces of information, together with the Preservica server context, provide the default means for addressing resources using the API.

The URL string has five components, these are:

• The transfer protocol, which is always http(s);
• The Preservica server address;
• A string invoking the Entity API, this is always "/api/entity";
• The resource type;
• The unique reference to the resource.

Note: For backward compatibility reasons, the Entity API is also available through /sdb/rest, but we recommend you update any references to use /api/entity.

Thus, the URL for a resource is simply:

For example, a Collection with reference 2b318ad7-d6a3-4112-940d-e02f3e6f3f2c, on an Preservica instance deployed at "sdb-server.com", would be addressed through the URL:

Note: The string here is collections and not collection. A full list of strings to use for specific data types can be found at Appendix A.

It is possible to return all collections by omitting the reference from the URL. This would be addressed through the URL:

Only "collections" (in reality, folders) can be retrieved through this endpoint. Attempts to access "deliverable units" or "files" will fail. Use the V6 Entity API if possible.

Making a Web Service Call

Calls to the REST web service are simply HTTP GETs to the relevant URL. Some Preservica credentials are required in the HTTP header so that the database lookup can be performed; these should be sent as the username and password for HTTP basic authentication.

Using the Resource Returned

What Information is Returned

The return of the web service call is an XML document containing an Preservica XIP fragment. For example, a request to the following URL identifies a top-level collection:

The body of the HTTP response is as follows:

Accessing Child Elements

In addition to the standard XIP fields, and any generic metadata fragments that are embedded by the resource, there is a generic metadata fragment which contains an Atom feed (as defined by the namespace http://www.w3.org/2005/Atom). This feed contains information about the immediate child elements of the resource.

Note: To include virtual collections in the result append includeVirtual=true to the URI

For each child element, an Atom entry element is added to the feed. The Atom entry includes:

• the child’s Preservica reference,
• some summary information, which depends on the object type,
• the child’s title, and most importantly,
• the URL by which the child can be accessed using a REST web service call.

This URL is the link tag of the Atom entry. In addition to the URL, this link tag contains information on the Preservica data type of the child element (the "rel" property), and the mime type of the child resource (the "type" property). Discovering all descendant elements of a particular resource requires recursive calls to these returned links.