Developer Blog - API Updates in Preservica 7.1

Preservica 7.1 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 middle of 2024.

Improved Summary

We have updated the in-product API summary in the documentation index page. As well as being a root page with links to the technical documentation for most of our APIs, there is now a descriptive summary for them within the page itself. (Use the expand arrows on the section for each API to see it.)

Some of the APIs have full explanations and use case examples. We'll be updating this page over upcoming versions to improve the information for the other ones.

Basic Auth for PAR

As I mentioned in the 7.0 post, we are phasing out Basic Auth across all of our APIs. As part of that plan, endpoints that require authentication on the PAR API in the Registry (endpoints under /api/Registry/par) now accept an access token like all of the other modern APIs.

Using Basic Auth to access these endpoints is now deprecated. If you are using automation (e.g. scripts) to access these APIs, please change them over to using access token based authentication. We plan to remove the ability to authenticate with basic auth in Preservica 7.4 – this will allow for EoP/LTS users to make the change after receiving the next LTS release (currently planned to be 7.3).

Exceptions – the following APIs are still accessible via basic auth, although if you can access them with a token it is better to do so:

• APIs that are following an external standard: CMIS and OAI-PMH. We recommend that, unless you're integrating with a system that uses those APIs to communicate, you use the Content and Entity APIs and access tokens instead.
• Some old v5 APIs which are still used by our desktop tools. You should be using the v6 equivalent APIs (mostly on the Entity API) with access tokens instead. These APIs are deprecated and could be removed at any time.

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.

Temporary User Challenges

Temporary users (managed through /temporary-users on the Admin API) can now be configured with a long expiry time. In this case, for security reasons, users may be sent a challenge code (typically via email) which needs to be entered to complete login, in a similar manner to two factor authentication.

When you attempt to acquire an access token with /acquire-temp-user, you might receive a 401 with a message needs.email.challenge. In this case, the user will be sent an email with a challenge accept link. You'll need to put up a message or log the failure and wait until the user has performed the challenge completion through the UI.

Challenge completion is done by the new /complete-challenge endpoint. You need the challenge token which will be in the email sent to the user. Like /complete-2fa, this endpoint returns a successful authentication result, including an access token, and a cookie if you pass the cookie=true.

Entity API

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

Changes since 7.0

• Getting information about a CO now has a new endpoint /content-objects/{ref}/generations/{genIndex}/bitstreams/{bsIndex}/storage-locations which returns the storage adapters that the bitstream is stored on. Adapter information is just a name at the moment; this may be augmented in future versions.

Authentication 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. Affected customers (using SAML with our existing approach) should have received emails from our CX team, and guides for setting it up for new customers will be added soon.

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

Changes since 7.0

• New endpoints under /idp-metadata allow you to fetch IDP metadata without saving it. This enables a preview of IDP information to show to a user before confirming that it's correct and saving it (with a PUT to /configuration). You can fetch IDP metadata from a URL, as with /configuration, and also by posting an XML metadata document, for the use case where your IDP is not accessible to Preservica or doesn't expose metadata publicly.

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.

Changes since 7.0

• There is a new endpoint at POST /{apiId}/generation to request the generation of a dataset that takes a long time to generate. The request body should contain parameters for the relevant data set. You can use the progress endpoint to track progress in generating the dataset. Once it's complete, you can use GET /datasets/{apiId} to retrieve the data.
• There is a new data set policy.impact which should be generated asynchronously. This data set shows the effect of a proposed migration policy if you were to enable automatic preservation.

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 7.0

• New endpoints under /migration/config/drafts allow for management of draft policies. A draft policy has the same form as a complete configuration, with all the profiles and rules together. Policies must have IDs that are referenced from the rules. Draft policies have no effect within the application, but you can use them to back a multi-stage edit process for users.
• Getting rules, either the list via /migration/config/rules or individually via /migration/config/rules/{id}, now accepts an expand parameter, allowing you to request more information if you need it to display to a user. The only expansion so far is entityMap, which will add entity titles (as well as refs) to the response, allowing you to show users a link as in our UI.