Developer Blog - API Summary in Preservica 6.11 and 6.12

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. APIs which haven't changed will no longer be listed in these posts. If you're new to the Preservica APIs then the documentation index page will take you to the technical documentation for most of our APIs. For a descriptive summary you can look through articles on this dev blog for the version the API was introduced in, or for those that have been around for a while then this article for Preservica 6.3) has the summary.

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

Preservica 6.12 is a Cloud-only release and is not a Long Term Support (LTS) release. These API changes will be made available to non-cloud environments with our next LTS release, currently planned to be around the start of 2024.

Authentication API

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

Changes since 6.10

• You can now request that endpoints which create or update your access token also put the token in a cookie. The endpoints are POSTs to: /login, /refresh, /complete-2fa, /acquire-external, /acquire-restricted, /acquire-temp-user. The access-token cookie will be delivered against the server domain and will be HttpOnly (i.e. not available in script).
• The AccessTokenResponse from those endpoints now includes a tenantValue, if you specify includeUserDetails. This is the value you need to construct login URLs for the new authentication approach (/auth/login/{tenantValue}). A reminder that this endpoint is not versioned and therefore this will change for all consumers – it's a new property in a JSON object so we don't expect that to cause you problems.
• All API endpoints on the main APIs will accept an access token in the access-token cookie as an alternative to the Preservica-Access-Token or Authentication: Bearer HTTP header.
• Several endpoints will automatically refresh your access token (i.e. return a new access-token cookie in headers) if it's near expiry. These endpoints are: /content/top-level-list (GET or POST); /workflow/instances (POST), /auth/configuration (GET or POST), /settings/migration/config/profiles (GET). (We will likely be adding a more explicit keep-alive mechanism in a future version.)

Taken together, these updates mean that if you are creating a user-facing browser app, you can allow Preservica to handle your session management, keeping the access tokens away from potential scripting attacks and making your code simpler. Request cookie=true when calling /login and related endpoints, and make sure your user flow calls one of the endpoints above, and the cookie will be kept alive during the user's session and used for all API calls without any further intervention.

Entity API

The Entity API is the main way we expose information about entities stored in your Preservica system.

Changes since 6.10

• If you have the merge and merge.in.place features enabled, you can now update an asset by merging in other assets via PUT to /actions/merges, similar to the existing POST but modifying an asset rather than creating a new one. This only works on assets created via /actions/merges or assets with no existing Preservation content.
• You can add a new representation to an existing asset with a POST to /information-objects/{ref}/representations. The POST body can be a zipped PAX, or a single file. It is your responsibility to ensure that the content you upload makes sense given the Preservation representation of the asset!
• Ingest from source: in addition to the existing upload-file and upload-package, you can also now POST to /ingests on SO and root to instruct Preservica to ingest content (single asset or an OPEX directory) from a known location within a Source (e.g. an S3 bucket).

Analytics API

This API offers data sets that you can use for reporting or analytics beyond what you can get through our pre-built reports and the Reports API. We plan to add more data sets to this offering in future.

This API is marked Provisional as we're still working on it and there may be breaking changes.

Changes since 6.10

• It's now possible to find out which datasets are available via a GET to /datasets, and information about a specific dataset via a GET to /datasets/{id}.

Settings API

This API allows the retrieval of information about settings (currently, only migration settings) on your Preservica system. This is equivalent to the Migration Settings page in the UI.

Changes since 6.10

• You can now query and update the automatic preservation configuration via /migration/config/auto-migration. You need the auto.remigrate feature enabled to turn auto-preservation on.

Administration and Management API

Use this API to manage authentication configuration, in particular information allowing you to set up SAML. This will allow you to pre-configure your tenant to be ready to use our new authentication approach when it is fully rolled out. There will be more information about this in the coming releases.

This API is marked Provisional as we're still working on it and there may be breaking changes.

Changes since 6.10

• You can now request the authentication type (not the full configuration) for a tenant through the unauthenticated endpoint GET /type/{tenant-value}. The tenant value is returned from the login endpoint when you request user details. You can use this to remember a tenant and decide whether to offer a different login experience for SAML versus LDAP login scenarios.

Webhooks

There is a new webhook (CHANGED_SECURITY_DESCRIPTOR) which will receive notifications when an entity has its security descriptor (security tag) changed. It will fire for every entity in a hierarchy tree and we have some upcoming work to improve scaling of web hook dispatch, so please don't subscribe to this if you perform this action on a deep tree. Like the move webhook, you will only receive information that the tag has changed on an entity, you'll have to use the Entity API to find the new tag (remembering that you might get a 404 if you can no longer see the entity with your API user's roles).

We've also changed the notification you receive slightly. The timestamp will now include a time zone. It will be in server time; for our cloud services this will normally be UTC.