API Summary in Preservica 6.5

In this post I'll give you a summary of the APIs in Preservica 6.5, and any new features contained within each. 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.4.1, 6.4.3 and 6.5). If you're new to the Preservica APIs then you can use the whole article as a reference.

Authentication API

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

If further information is required, detailed breakdown of this process has been provided in previous API updates.

No changes since 6.4

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!

Changes since 6.4

• The ability to action edits to metadata, such as to update/replace/clear/remove fields from metadata - on a list of entities or on a result of solr search query. This can be done via a POST at /.../actions/metadata-edits

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.

No changes since 6.4

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.

Changes since 6.4

• There is now the possibility to register and unregister workflow definitions for specified tenants. These PUT requests can be made to /.../definitions/{id}/register and /.../definitions/{id}/unregister respectively.

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.4

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.4

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.

Changes since 6.4

• Through a PUT, permissions can be updated at /.../security/permissions. This allows the submission of a list of permissions to update, and returns the updated list after these changes have been performed.
• It is now possible to GET a list of available operations under /.../security/operations.
• A new role can be created, or deleted, under /.../security/roles.

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.4

Storage API

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

No changes since 6.4

Security API

This API provides security information visible for the current user. (Security configuration is done through the /security section of the Admin API).

No changes since 6.4

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.

No changes since 6.4

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.4

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.4

Settings API

This is a new API, intended to allow the retrieval of information about settings on your Preservica system.

• It is now possible to obtain information about profiles and rules within the system either as lists or individual instances. You can obtain this information under /.../migration/config

Location API

This is a new API providing information about locations (also known as sources) configured in Preservica. Currently it only offers information about upload locations (i.e. ingest sources). Use this API if you need to upload content into Preservica which is too large or inconvenient to send to ingest endpoints on the Entity API.

• It is possible to retrieve a list of upload locations configured to the system, through a GET to /.../upload. This endpoint does not return credentials for any of these locations, merely a list of the locations themselves.
• Further to the previous new endpoint, a set of temporary access credentials to a particular upload location in the system, referenced by that location's {id}, can be obtained through a GET under /.../upload/{id}/upload-credentials.