Developer Blog - API Summary in Preservica 6.8

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 a previous edition of this blog (for 6.3, here) has a summary of each API, apart from those added in later versions (Metadata/Reference Metadata: 6.7; Settings/Location: 6.5; Security: 6.4).

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

Preservica 6.8 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 6.9.

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

This API has been updated to support two factor authentication. If two factor authentication is enabled on your tenant, then this API has changed in the following way:

• The response to login may now give you a response indicating that 2FA needs to be completed. This will be a HTTP 401 (because you are not yet fully authenticated), with an error message of either "needs.2fa" or "needs.2fa.setup". It will also contain a continuation-token.
• If you receive "needs.2fa" you should generate or prompt the user for a valid authenticator code, and send that with the continuation token to the new complete-2fa endpoint. Our 2FA follows RFC4226/6328 for time based one time passwords (the same as Google Authenticator etc). Because it's time based, if you're generating a token, make sure the clock on the system is accurate.
• If you receive "needs.2fa.setup", the response will also contain a secretKey. This is the authenticator key which you should save, or show to the user in a way that they can save (e.g. we use it to show a QR code that an authenticator app can save). As above, you need to generate or prompt for a valid authenticator code using this key and make a call to complete-2fa.
• The response from complete-2fa is the same as you get from login if 2FA is disabled, containing an access token that you can use as normal.
• Failures: If a user enters an incorrect code too many (3) times, their account will be locked and a manager will need to unlock them from the 2FA configuration page. The number of failures and maximum attempts will be returned in the failure response.

Metadata API

This API allows you to manage the new view of descriptive metadata. There are endpoints under /forms to manage metadata forms, which are the way to define how descriptive metadata should be viewed and edited in a UI, and /groups to manage metadata groups, which let you define some descriptive metadata without specifying an XML schema.

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

Changes since 6.7

• It is now possible to delete a form via DELETE /forms/{id}.
• The response for GET /forms and GET /forms/{id} has been updated to better align with our data model.
• There is a new set of endpoints under /groups for CRUD operations on metadata groups.
• There is a new endpoint at /indexed-fields which returns similar information to the endpoint with the same name in the Content API, but also allows you to show reference metadata field links.

Reference Metadata API

This API allows you to view, update and manage reference metadata (the same data that is available through Data Management > Reference Metadata in the UI). Endpoints under /records manage data within tables, and endpoints under /tables manage the tables themselves.

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

Webhook API

This is a new API which allows for registration of web hooks to be called by Preservica when particular actions happen within the system. It needs to be configured and is currently restricted to only a few actions. We'll be adding to this capability in future.