API Summary in Preservica 6.4

In this post I'll give you a summary of what APIs we have in Preservica 6.4, and what new features you might be interested in.

If you've been using Preservica for a while and just want to know what changed, you can look for the relevant paragraph at the end of each section, and for more details, you can look at the release notes from the three versions (6.3.1, 6.3.2 and 6.4). If you're new to the Preservica APIs then you can use the whole article as a reference.

Most of our APIs also have online documentation which you can get to from this index page.

Authentication API

Before you use any of our other APIs, you'll need to get an access token through this one.

In most cases that will mean submitting your user name and password to the /login endpoint. It's also a good idea to send the tenant – ask your Preservica contact if you don't know what your tenant name is. These parameters must be passed in the post body and the format must be x-www-form-urlencoded:

The response to this (assuming your credentials are valid) will give you a JSON response containing an access token:

You can then use the access token (in the token field) to authenticate with our other APIs, by setting the Preservica-Access-Token custom header, or a Bearer type Authorization header.

If you include the optional parameter &includeUserDetails=true then you will receive additional information including the tenant and roles, which can be useful for building a user facing application:

Token Lifetime and Refresh

Newly created access tokens last for 15 minutes (this is the validFor field in the response). Before that token expires, you will need to generate a new one. You could just request a new token with credentials each time, but in a user facing scenario this means you need to request the password each time. Instead, it's better to use the refresh token with the /refresh endpoint.

Submit the current access token as the authentication, and the refresh token in the refreshToken parameter. You will receive a response similar to what you get from /login, with a new access token and new refresh token.

Note that unlike OAuth 2, you can't use a refresh token after the initial access token expires, so you can't wait for a 401 and then refresh, or have 'remember me' like functionality where you store a refresh token. You must proactively manage your token refreshes.

No changes since 6.3

• The tenant parameter to /login is no longer mandatory, and the extended response includes the tenant.

Entity API

The Entity API is the main way we expose information about entities stored in your Preservica system. It is a RESTful XML API which has two main types of resource: resources returning a list, which will typically include a wrapper with an entry for each item in the list, and resources for a single object, which will include more details about the object. Responses typically include links to other relevant resources. List type resources often accept paging parameters (start and max).

Remember this article is not a full reference and for more details of available endpoints, visit the Swagger documentation!

If you want a read only view with more summary information presented to you, consider the Content API.

For example here is a response from /root/children, which is a list of entities:

Each item in the response list is a link to another resource, in this case an entity resource for the top level SOs, and the response also contains information about the paging and links to other relevant resources. And here is a sample entity details response:

In this case the response contains a single object (the XIP InformationObject) but there are more links to related resources.

Entities

Each of the three types of entity in the main object hierarchy (Structural Object, Information Object, Content Object) are available through similar routes, at /{object-type}/{ref}, e.g. /api/entity/information-objects/a9e1cae8-ea06-4157-8dd4-82d0525b031c. You can retrieve other information about an entity from the linked subresource endpoints. Remember that Folder and Asset are friendly names for SO and IO.

Information objects also contain information about representations (representations subresource and related requests). Content objects allow access to their generations and bitstreams (generations subresource and related requests), including downloading the content of individual bitstreams.

Making Changes

The Entity API also allows you to make changes. Most things you can change are made available as a POST request to a list resource (e.g. add an identifier through /.../identifiers) to create a new object, or a PUT request to an individual subresource (e.g. update metadata through /.../metadata/{mref} to update an existing one. To update something you'll typically need to get the relevant ID from a GET request to the list endpoint (/structural-objects/{entityRef}/metadata in this case).

There are also some endpoints that allow you to upload new content:

• POST to an SO to upload a package for ingest. This is equivalent to running the Standard Ingest workflow in that folder, and selecting the package file that you upload.
• POST to a CO to replace deprecated content. This is equivalent to the Replace button in Explorer when looking at the CO in the Advanced properties view.

Events and Changed Entities

You can retrieve the event actions associated with a single entity from the /event-actions subresource of the entity. You can also reach events through the /events route, and the actions associated with a particular event by the /event-actions subresource of an event. (Reminder: A single event can have actions against multiple entities.) Event and event action listings are paged in the normal way.

You can also get a list of all the entities which have changed recently via /entities/updated-since. This is an alternative to the most common use of OAI-PMH and allows you to keep a UI or third party system up to date without having to re-inspect the entire entity tree.

Long Running Tasks, Actions and Progress Tokens

Some actions you can trigger may take longer than is reasonable to hold a REST request open for. This includes uploading content (which must pass through our ingest pipeline), and also actions which can affect a large part of the hierarchy (moving or locking the structure under an entity). These actions will return a progress token, which you can pass to the /progress/{token} endpoint to track the progress of the action. You'll have to poll this endpoint to get the status.

Sometimes these actions will also be made available in a list under /actions. For example, when you initiate an export by POSTing to /exports under an SO, as well as returning a progress token, it will also cause the export to appear at /actions/exports. If an action provides this type of endpoint it will give you more information than the general progress endpoint.

Some tasks may also create a process which you can watch via the Process Monitor API, but there is no link between progress tokens and processes so finding the right process can be difficult.

Access Control

Actions on entities, including viewing them, are controlled by the security tags on those entities, and the permissions that the current user's roles give them on those entities. For example to retrieve any part of an entity you need Read Metadata permission on its tag, and to update it you need Update Metadata permission on its tag.

Versioning

A reminder that the Entity API is versioned (see this blog post for details of what that means). We have updated the version on both the Entity API XML schema (http://preservica.com/EntityAPI/v6.4) and the XIP schema (http://preservica.com/XIP/v6.4).

This means that:

• If you're using the versioned endpoint at /api/entity/v6.3, nothing will change for you until you modify your code to request /api/entity/v6.4 instead. When you do that, you need to manage the new namespaces.
• If you're using the unversioned endpoint, the responses will now serve the new namespace. If you're doing this, your code should be able to accept a change in namespace when we upgrade Preservica.

If you have a custom XIP to CMIS transform, you will have to change it to target XIP version 6.4. Remember that you can set the metadata field to be used in Title and Description for Content API/CMIS object details requests (on the Collection Properties configuration page), so most of you shouldn't need this transform.

Changes since 6.3

• Create and delete links via POST and DELETE endpoints at /.../links
• Multiple entities can be deleted in a single action by POSTing to /actions/deletions. This works the same as deleting an entity individually (you get a progress token to follow).
• You can retrieve hierarchy information when getting the entity from /.../{ref}. Request expand=hierarchies to get this. We didn't include it by default because retrieving that information has a cost.
• If you have the Physical Assets feature enabled, you can create an Asset by POSTing to /information-objects.
• You can request additional information on entity lists from /root/children and /structural-objects/{ref}/children using the expansion syntax (expand=... in the query). This lets you get the information you need to populate a UI with icons and overlays in a single query. For SO children you may also specify virtual-path if you accessed the SO via a virtual hierarchy, which will affect the overlay status of the children.

Content API

This API provides a read only view of your archive, search capabilities, asset download and information about entities suitable for a public access portal (in fact it backs our Universal Access portal). It is described in the SDK: Content API document as well as each endpoint being described in the Swagger doc.

Endpoints on this API typically take query parameters or a form encoded POST body, and return JSON.

Searching

Many requests on this API (obvious ones like /search and /search-within, but also those returning a list of entities at /top-level-list and /object-children) do a search against Preservica's search index. The form of all of these endpoints is similar, and the complexity is in creating the q parameter which defines the query. The Swagger doc for each of these requests describes how to set up the q parameter.

Search queries all permit you to send a POST request so the q parameter can be sent in the POST body, as it can be too long or complex to realistically put in a GET query.

The result from these endpoints gives you the objects that matched the search, and other information as requested in the query, e.g.:

The list of object IDs will be the same length as the metadata list, and you can merge those two lists together to get summary information you can display in the search result for each entity. You can also use this information together with the Entity API to retrieve more details about an object. Facet data will also be returned for each facet you request.

Object Details

The /object-details endpoint takes an object ID (with the sdb:IO type prefix) and gives you back metadata you can use to display the entity. The form of the response to this will be something like:

The metadata that is returned is a result of running the CMIS transform for relevant descriptive metadata fragments (in this case I have set up an OAI DC to CMIS transform). There is an extensive set of cmis: and sdbcmis: properties which I won't go through here.

No changes since 6.3

Workflow API

This API lets you control most aspects of workflow management, including starting, stopping and terminating workflows, submitting results to tasks which normally require human interaction, and uploading definitions and contexts. This API is described in the SDK: Customisation API document as well as the individual endpoint documentation.

Note that requests to this API go to the /sdb webapp on the application server, not the API server as most of the other APIs. This is because workflows are managed in that webapp.

No changes since 6.3

Process Monitor API

The Process Monitor API lets you see information about ongoing processes, messages associated with them, and a day-by-day history of long running processes (large ingests). It is most useful for tracking OPEX ingests, but normal ingests also create a Process which you can watch with this API. This API exposes the same information available through the Monitor webapp, or the Notifications panel on SDB and Explorer, if you have those enabled.

No changes since 6.3

Report API

The Report API allows you to retrieve and run reports. Like the Entity API, it has a progress endpoint to allow you to track long running reports, and an /actions/reports endpoint to see running or completed reports.

No changes since 6.3

Administration and Management API

This API allows you to perform some administrative and management tasks, which you'd normally do through the Administration menu in the main application. Endpoints on this API typically require Manager or Admin role.

Versioning

We are going to start versioning this API, with v6.4 being the baseline. Versioned endpoints at /admin/v6.4 will be available from 6.4.1, and the same version management considerations as for the Entity API will apply from 6.5 onwards.

Changes since 6.3

User API

This API allows you to get information about your own user account after logging in (for example to display a Profile page in a UI), and to manage it (limited to requesting password resets at the moment).

No changes since 6.3

Storage API

You can use this API to discover your storage quota limit. This is currently only relevant in the context of Preservica Starter.

Security API

This is a new API which provides security information visible for the current user. (Security configuration is done through the /security section of the Admin API). In 6.4 the only available information through this API is the security tags on which the current user has permissions, and what permissions those are.

PAR (Registry) API

This API is for getting information from the Preservica Registry, and updating it if you have institution specific preservation needs. You need Registry Admin role to make any updates (which, on our hosted systems, is only available to Preservica staff). See this blog post on PAR for more information about PAR and how to use this API. Note that this API is on the Registry webapp (on the application server), not on the API webapp.

Changes since 6.3

• We've added the concept of a Recommended Process (/recommended-processes), which is an indication from the registry manager to the preservation system that something ought to be run against existing content. This is foundational work for our auto-preservation functionality which you'll hear more about in the coming months.
• Rule sets (/rulesets) can now be filtered by the Preservation Actions or Business Rules that are referenced from the rule set.

OAI-PMH

OAI-PMH is a standard protocol through which archival systems can exchange information. Preservica exposes data as an OAI-PMH data provider through the /OAI-PMH route. This API is described in the SDK: Content API document.

The main use of OAI-PMH is to list recently changed records. If you aren't integrating with an OAI-PMH consumer, consider using /entities/updated-since on the Entity API.

No changes since 6.3

CMIS

CMIS is a standard protocol through with content management systems can exchange information. Preservica exposes a limited subset of data through a read only CMIS 1.1 endpoint at /api/cmis/atom. (You can't use CMIS to create or update entities in Preservica.) The information available through CMIS is similar to that exposed by the Content API endpoints for top level entity listing, object details, searches and object children. Like the Content API, the information returned in the CMIS Metadata extension is generated from the relevant descriptive metadata fragments through their CMIS transform (e.g. a MODS to CMIS transform if you have MODS metadata).

The Content API is more widely used and more robust so consider using that if you aren't integrating with a CMIS consumer.

No changes since 6.3