Developer Blog - API Updates in Preservica 9.2

For a summary of all our APIs, you can use the documentation index page.

Deprecation notice reminder

/api/accesstoken/acquire-external and the SOAP web service for managing workflows both remain deprecated, and both continue to be available in 9.2. Please do get in touch if you'd like assistance migrating away from these APIs.

Breaking change: Metadata Quality Control is now Metadata Quality Check

The Metadata Quality Control API introduced in 9.1 has been renamed to the Metadata Quality Check API, and its base path has changed from /api/metadata-quality-control to /api/metadata-quality-check. The endpoints, request parameters and response bodies themselves are unchanged, so if you are using this API you only need to update the base path.

The related entitlement feature module has also been renamed from metadata.quality.control to metadata.quality.check, which is visible through GET /api/admin/features/usage and GET /api/entitlement/limits.

Admin API

This API allows you to configure your Preservica system.

Changes since 9.1

• We've added a new GET /opt-ins endpoint, which lists the available opt-ins and whether each one is enabled for your tenancy
• We've added a new PUT /opt-ins/{optInKey} endpoint, which enables or disables an opt-in for your tenancy. This requires the config manager permission
• Opt-ins are how you tell us that you want an AI powered feature to be used on your content. They are separate from feature entitlements, so a feature can be entitled to your tenancy and still be unavailable until you have opted in to it. The first opt-in available through these endpoints is ai.metadata.quality.check, for the Metadata Quality Check feature
• Opting in and out is recorded in your configuration history, so GET /config-events now returns events with the new command types OptIn and OptOut in a new opt_in category. Both are also listed by GET /config-events/filter-info so that you can filter on them
• Please note that these opt-in endpoints are likely to move to the Entitlement API in a future release, and their shape may change slightly as we add more AI features. We'll call out any change in a future post, but do get in touch if you are planning to build against them

Metadata Quality Check API

This API allows you to review the results of metadata quality clustering analyses.

Changes since 9.1

• The base path has changed from /api/metadata-quality-control to /api/metadata-quality-check, as described above
• All endpoints in this API now also require the ai.metadata.quality.check opt-in to be enabled for your tenancy, in addition to the existing feature and permission requirements. If the opt-in is not enabled you will receive a Forbidden response. You can check and set the opt-in with the new Admin API /opt-ins endpoints

Entity API

This API is for creating, reading, updating and deleting entities and their metadata.

Changes since 9.1

• We've added a new GET /information-objects/{ref}/external-sync endpoint, which re-evaluates your external sync policy live and returns whether the asset is currently externally visible, along with the ID of the policy that decided it. No state is stored, and the endpoint returns a Forbidden response if external sync is not enabled for your tenancy
• The MetadataClustering and MetadataClusterEdit actions on POST /actions now also require the ai.metadata.quality.check opt-in to be enabled for your tenancy
• Retention policies with a DELETE expiry action now recognise a MergedEvaluation value in expiryActionParameters. When true, the manual Evaluate Deletion step is merged into the approval step when the policy expires. Policies which don't set it, including any policy configured in the classic interface, keep the existing two stage deletion flow
• The XIP schema has been published as XIP_v9.2, adding LEGAL_HOLD as a valid restrictionType value alongside LOCK and DELETE

Analytics API

This API allows you to retrieve analytics datasets about your Preservica system.

Changes since 9.1

• The dataset description returned by GET /datasets and GET /datasets/{apiId} is now fully documented as a schema rather than a generic object, and includes a new isRoutedByID field. This indicates that a dataset has multiple instances which are addressed by an additional routing ID

PAR API

This API gives access to the Preservation Action Registry information held in your Preservica system.

Changes since 9.1

• GET /file-formats accepts a new search filter header. This matches any file format whose PUID, name or extension contains the supplied text, case-insensitively. Unlike the existing name filter, this is a substring match rather than an exact match

Changes affecting all APIs

• As usual, each API now has a v9.2 versioned path (for example /api/entity/v9.2/...) and responses use the v9.2 XML namespaces. Clients that need the previous response format can continue to request v9.1