Developer Blog - API Updates in Preservica 9.4

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

Entity API

This API allows you to view and manage entities within Preservica.

Changes since 9.3

• The XIP v9.4 schema adds SECURITY_TAG to the restrictionType values. This restriction applies to an asset that is assigned a retention policy with the "change security tag" expiry action. While that assignment is in place, you can't change the asset's security tag manually
• When you assign a retention policy with the "change security tag" expiry action to an asset (POST /information-objects/{ref}/retention-assignments), you now also need permission to change permissions on the policy's target security tag, as well as on the asset itself

Analytics API

This API allows you to get analytics data. These endpoints require the 'reports' feature.

The following changes pertain specifically to the so-details dataset.

Changes since 9.3

• POST /datasets/{apiId}/{routingId}/generation now accepts an optional levels form parameter for the so.details dataset. This sets how many folder levels below the target folder are included: leave it out for the default of 1 (the target folder plus its direct child folders), use 0 for the target folder only, a positive number to go that many levels down, or -1 for the entire subtree. Other values return a 400 response
• Rows returned by GET /datasets/so.details/{routingId}/results have a new depth field (0 for the target folder), and parentRef gives each folder's own parent, so you can rebuild the folder tree when you ask for more than one level
• The CSV returned by GET /datasets/so.details/{routingId}/results/csv has a new depth column between parentRef and directChildAssets. If you read the columns by position, please update your code
• Completed routes returned by GET /datasets/{apiId}/routes include a new levels field showing the depth the dataset was generated at
• Results generated before 9.4 don't have the new fields. Generate the dataset again to get them

Report API

This API allows you to run reports and download the results.

Changes since 9.3

• GET /definitions now includes the Entity Checksums Export (when its workflow is active), and you can view it with GET /definitions/{apiId}
• You can run the Entity Checksums Export with POST /definitions/{apiId}/reports. The request body is optional for this report. It takes an optional generation report parameter of Original (the default) or LatestActive. Other values are accepted by the request, but the export then fails
• GET /actions/reports now includes Entity Checksums Export runs, as well as standard reports. You can download a completed export with GET /actions/reports/{progressToken}/content. It's a ZIP file containing entity-checksums.csv

Authentication Management API

This API allows you to configure authentication for Preservica.

Changes since 9.3

• The AuthConfigProxy model has a new idleTimeoutMins field. You can use it with GET /configuration and PUT /configuration to view and set the inactivity timeout for sessions on your tenancy. If it isn't set, the default of 15 minutes applies
• The default maximum session lifetime (maxSessionLifetimeMins) is now 8 hours, rather than 18 hours
• PUT /configuration now returns a 400 response if idleTimeoutMins is outside the range 1 to 15, or maxSessionLifetimeMins is outside the range 60 to 1080 (previously 0 to 10080). These limits are checked even if you use the no-validate parameter. Existing tenancies with a maximum session lifetime outside the new range have been moved to the nearest allowed value
• PUT /configuration no longer logs all users out if you only change the session settings (maxSessionLifetimeMins or idleTimeoutMins). Because PUT replaces the whole configuration, send all the other settings back unchanged. Any other change still logs all users out

Authentication API

This API allows you to acquire access tokens for use with the other APIs.

Changes since 9.3

• Access tokens from /login, /refresh, /complete-2fa, /acquire-restricted, /complete-challenge, /acquire-external and /acquire-temp-user are now valid for the tenancy's inactivity timeout, rather than a fixed 15 minutes. The default is still 15 minutes. A token from /refresh won't last beyond the end of the session, so near the end of a session validFor may be shorter
• Access tokens now stop working as soon as they expire, and you can't refresh an expired token
• For SAML logins, the session lifetime now comes from the session expiry (SessionNotOnOrAfter) sent by your identity provider, if it sends one, rather than from maxSessionLifetimeMins

Admin API

This API allows you to configure your Preservica system.

Changes since 9.3

• Changes to session settings are now recorded as config events with the new SessionSettingsChange command type, under the security category. You can filter for these with GET /config-events, using category=security and command_type=SessionSettingsChange

Webhook API

This API allows you to subscribe to notifications of events within Preservica.

Changes since 9.3

• Server errors (5xx responses) now return a generic message instead of internal error details