Developer Blog - API Updates in Preservica 9.3

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

Breaking change: opt-ins have moved to the Entitlement API

The opt-in endpoints we added to the Admin API in 9.2 have been removed and replaced by equivalents in the Entitlement API. If you integrated against /api/admin/opt-ins in 9.2, you will need to update your client for 9.3.

• GET /api/admin/opt-ins and PUT /api/admin/opt-ins/{optInKey} no longer exist. Use GET /api/entitlement/opt-ins and PUT /api/entitlement/opt-ins/{feature} instead
• The new endpoints use JSON rather than XML.
• Opt-ins are now identified by the name of the feature they control, not by a separate opt-in key. The Metadata Quality Check opt-in is therefore metadata.quality.cluster in 9.3, where it was ai.metadata.quality.check in 9.2. Your existing opt-in state is migrated on upgrade, so no action is needed beyond using the new name
• Opting in and out continues to be recorded in your configuration history, with the OptIn and OptOut command types in the opt_in category, reachable through GET /api/admin/config-events as before. The command now records the feature name
• Reading the opt-ins requires no particular permission; changing one still requires the config manager permission.

Entitlement API

This API tells you which edition, add-ons and features your tenancy holds.

Changes since 9.2

• We've added GET /opt-ins and PUT /opt-ins/{feature}, described above
• We've added a new GET /editions endpoint, which lists all the editions that exist, each with its name and display name. It requires the system admin permission
• We've added a new GET /feature-modules endpoint, which lists all the feature modules that exist, each with its name and display name. Feature modules group features and limit values together, and are either included in an edition or awarded as an add-on. It requires the system admin permission

Admin API

This API allows you to configure your Preservica system.

Changes since 9.2

• GET /opt-ins and PUT /opt-ins/{optInKey} have been removed, as described above
• The ai.metadata.quality.check.opt.in and ai.vector.search.opt.in system properties have been removed, and are no longer returned or accepted by the /system-properties endpoints. Both opt-ins are now held in the entitlement system and are managed through PUT /api/entitlement/opt-ins/{feature}. Any value you had set is migrated on upgrade

Entity API

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

Changes since 9.2

• We've added a new DELETE /information-objects/{ref}/representations/{specifier} endpoint, which permanently deletes a representation and all the content within it. It requires the Transform permission and Update Metadata permission on the asset's security tag. Preservation representations cannot be deleted, and an attempt to delete one returns a Bad Request response
• GET /{entity-type}/{ref}/event-actions accepts a new commandTypes query parameter, a comma separated list of event action command types to filter by. Omitting the parameter returns every event action, as before
• Retention policies accept a new CHANGE_SECURITY_TAG expiry action. When the policy expires, the target security tag is taken from expiryActionParameters in JSON format, for example {"SecurityTag":"open"}. This applies to both POST /retention-policies and PUT /retention-policies/{ref}
• POST /actions/ingests accepts two new optional elements within WebCrawlSubmission: PageLimit, the maximum number of pages to retrieve, and ScopeType, which bounds how far the crawl may travel from the seed URL. Valid scope types are PREFIX, PAGE, HOST and DOMAIN. As with the other web crawl parameters, if you override any of them when using an ingest config, all of them are overridden
• POST /actions/metadata-clustering and POST /actions/metadata-cluster-edits now check the metadata.quality.cluster opt-in rather than the old ai.metadata.quality.check one. A tenancy that is entitled to the feature but has not opted in gets the not-opted-in response; one that is not entitled at all gets the unavailable-feature response
• The XIP schema has been published as XIP_v9.3. It is identical to XIP_v9.2 apart from the namespace, so no changes to your documents are needed

Content API

This API allows you to search for and retrieve content.

Changes since 9.2

• /search and /search-within accept a new nlq field within the q query JSON, holding a natural language query. When it is present, results are ranked by semantic similarity using vector search rather than by keyword match. This field is released as an early access preview and is provisional: its name, shape, validation rules, response scoring and gating may change in a future release without a v2 API break, so expect to update any client you build against it
• Natural language search requires the ai.vector.search add-on and the matching tenancy opt-in, which you take through PUT /api/entitlement/opt-ins/ai.vector.search. Without both, a request carrying nlq returns a Forbidden response
• nlq and q cannot be combined in one request; use one or the other. An empty nlq, or one longer than 512 characters, returns a Bad Request response. Filters, facets, sort and paging continue to work as normal alongside nlq
• The version value in the response wrapper returned by /search and /search-within has changed from 1 to 2, reflecting the new scoring fields. The rest of the wrapper is unchanged

Analytics API

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

Changes since 9.2

• We've added a new entity.access dataset, "Entity Access History", which lists the 'View entity' access events your users have generated. It accepts startDate, endDate, userName, entityRef, entityType, sort, start and max parameters, and sorts by created, username, entityref, entitytype or title, newest first by default. It requires the config manager permission and the entity access events feature
• The so.details dataset, which was listed but not yet implemented in 9.2, is now available. It is an ID-routed dataset: the routing ID is the reference of the folder you want, and the results give one row per folder, being the target folder and each of its direct child folders, with asset and folder counts and total storage size. Rows are filtered by your own read metadata permission, so you see only the folders and tags you are allowed to see
• Following on from that, the ID-routed endpoints introduced in 9.2, GET /datasets/{apiId}/{routingId}/results and POST /datasets/{apiId}/{routingId}/generation, are now generally available
• We've added a new GET /datasets/{apiId}/{routingId}/results/csv endpoint, which returns the same data as the JSON /results endpoint as text/csv, with one row per folder
• We've added a new GET /datasets/{apiId}/routes endpoint, which lists the routes an ID-routed dataset currently has. Each route gives the target route, its name, the generation date and a status of either COMPLETED or RUNNING; a route that has a completed dataset and a regeneration in progress is listed once, as COMPLETED. A valid apiId with no routes returns an empty list, and an apiId that does not support route listing returns a Not Found response. The endpoint is paged in the usual way

Process API

This API allows you to start processes, and to retrieve and update their configuration.

Changes since 9.2

• POST /ingest/configs and PUT /ingest/configs/{id} accept two new optional parameters on web crawl configurations, matching the ones added to the Entity API ingest action: pageLimit, the maximum number of pages to retrieve, and scopeType, which must be one of PREFIX, PAGE, HOST or DOMAIN. An unrecognised scope type is rejected as a validation error

Metadata Quality Check API

This API gives access to the results of the AI powered Metadata Quality Check feature.

Changes since 9.2

• All of the endpoints now check the metadata.quality.cluster opt-in rather than the old ai.metadata.quality.check one, and the opt-in is taken through PUT /api/entitlement/opt-ins/metadata.quality.cluster. As in the Entity API, a tenancy that is entitled to the feature but has not opted in is told that it has not opted in, while one that is not entitled is told that the feature is unavailable. There is no change to the endpoints themselves or to the data they return