Developer Blog - API Summary in Preservica 7.0

This post provides you with a summary of the API updates we have made in Preservica 7.0.

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 7.0 is a Long Term Support (LTS) release. These API changes will be made available to non-cloud environments as this version is made available to you. The LTS release is currently planned to be around the summer of 2024. If you're coming from the previous LTS release (6.9), you should also catch up with changes from 6.9 to 6.10 and 6.10 to 6.12 as well as the changes in this post.

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.

Basic Auth

We are no longer supporting Basic Auth for most of our APIs. You will need to use the Authentication API to authenticate with almost all of our APIs.

As far back as Preservica 5.9, we have recommended that API consumers use the Authentication API to fetch a token, and use the token header and token refresh mechanism to authenticate with further requests. This means you only need to send user credentials over the Internet once, and your API consumer does not need to hold onto them, which is more secure.

More recently we've made updates to how access tokens are accepted, so you can pass them in an Authentication HTTP header (making it easier to integrate with REST libraries), or allow the browser to manage the authentication via cookies if you are using the API within a user-facing browser context.

The best practice for using authenticated APIs is:

• If you are calling our APIs in a browser context, for example a custom portal: make a request to /login from your user login form, passing cookie=true. Perform API requests without worrying about authentication in your script, but handle a 401 response to return to a login flow. You may periodically POST to /refresh with cookie=true (see below) to keep a session alive
• If you are calling them from a back end context (e.g. script driven automation) which doesn't manage cookies, use the /login and /refresh endpoints to acquire and manage the token, as described in the API summary from 6.3 – though you may now pass the token in an Authentication: Bearer {token} header if more convenient.

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.
• The Registry PAR API. If you need to update the Registry, you still need to use basic auth. Most of you won't be doing that. (You do not need to authenticate at all to read Registry information.) We will be changing this in upcoming versions.
• 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.

Changes since 6.12

• A new endpoint has been added to explicitly revoke the current session, a POST to /close-current. The current session, including all associated access tokens (e.g. those generated from a refresh), will be closed.
• If you call /refresh with cookie=true, you no longer need to provide a refresh token. The current token (from cookie) will be refreshed if needed and a new cookie will be set. You can use this to keep a session alive. If you do so, it is your responsibility to implement sensible timeout and session protection logic.

Entity API

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

Changes since 6.12

• The endpoint we added in 6.12 to POST to /information-objects/{ref}/representations now allows you to specify a source for the new content, as an alternative to POSTing the file content.

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. 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.12

• A new GET endpoint at sp-metadata will retrieve SAML Service Provider metadata in a JSON format. This is the same information that is available from /auth/saml/sp-metadata.

User API

This API allows you to get information about your own user account after logging in (for example to display a Profile page in a UI), and to manage it.

Changes since 6.12

• We have added a new endpoint at GET /sessions to show information about all current active sessions for the user making the request. Note that this currently excludes sessions using the old web applications (/sdb, /explorer etc), though in future these sessions will also be included.