Developer Blog - API Summary in Preservica 6.6 and 6.7

This post provides you with a summary of the APIs we have in Preservica 6.7 (including changes made in 6.6), and the latest new features.

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, and for more details, you can look at the release notes from the relevant versions (6.5.1, 6.5.2, 6.6, 6.6.1, 6.7). 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 (Settings/Location: 6.5; Security: 6.4).

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

A note about our version numbers: From 6.6 onwards, we are changing what our version numbers mean. Up to now, the "x.y.0" versions have been the Long Term Support (LTS) releases which have been made available to non-cloud customers. We are changing how that works so "x.y.0" releases indicate a change of platform, whereas interim releases (e.g. 6.7.1) will be UI-layer only. In our new model, releases like 6.5.1 and 6.5.2 would be given "x.y.0" type numbers. We are still planning to mark a release as LTS every three releases (so the next one will be 6.9.0) at the same frequency as before, just the numbering has changed. But this obviously affects API consumers as the API version is linked to that part of the version number.

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.

No changes since 6.5

Entity API

The Entity API is the main way we expose information about entities stored in your Preservica system. It is a RESTful XML API which has two main types of resource: resources returning a list, which will typically include a wrapper with an entry for each item in the list, and resources for a single object, which will include more details about the object. Responses typically include links to other relevant resources. List type resources often accept paging parameters (start and max).

Remember this article is not a full reference and for more details of available endpoints, visit the Swagger documentation!

Changes since 6.5

• Since 6.5.0 you have been able to create a new asset as a result of a merge operation via /actions/merges. This will create a new asset linked to the content in the original assets. Those originals will not be touched; if you no longer need them you can delete them afterwards. Like other /actions resources, this will return a progress token to track the progress of the merge.
• You can now perform a move of multiple entities in a single action via /actions/moves. This works the same as using PUT to /{object-type}/{ref}/parent-ref, returning a progress token to track the move, but allows you to move multiple items in a single request.
• If you have the CO Order feature enabled, you can re-order the content objects within a representation post-ingest with a PUT to /information-objects/representations/{specifier}/{count}/content-objects.
• We've fixed an issue where ordering in the results of /entities/updated-since could be inconsistent between pages.

Content API

This API provides a read only view of your archive, search capabilities, asset download and information about entities suitable for a public access portal (in fact it backs our Universal Access portal). It is described in the SDK: Content API document as well as each endpoint being described in the Swagger doc.

Changes since 6.5

• You can now export search results from the Content API using /search-export. This will generate the same CSV as using the "Export results as CSV" option from Explorer (including the 5000 item limit). Like other query accepting endpoints, it can be called as a GET, or as a POST if your search criteria are too complex to fit in a query string. You need the advanced.search.export feature enabled to use this endpoint; if you were previously able to do this in Explorer then the feature should be enabled for you.

Metadata API

This is a new API to manage the new view of descriptive metadata. In 6.7, there are endpoints under /forms to manage metadata forms, which are the new way to define how descriptive metadata should be viewed and edited in a UI.

Reference Metadata API

This is a new API to retrieve reference metadata (the same data that is available through Data Management > Reference Metadata in the UI). At this time there are only GET endpoints to retrieve data about existing tables, there are no endpoints to update or add data to tables or to change the configuration of tables themselves. We anticipate that extensions like that will happen in future.

Workflow API

This API lets you control most aspects of workflow management, including starting, stopping and terminating workflows, submitting results to tasks which normally require human interaction, and uploading definitions and contexts. This API is described in the SDK: Customisation API document as well as the individual endpoint documentation.

Note that requests to this API go to the /sdb webapp on the application server, not the API server as most of the other APIs. This is because workflows are managed in that webapp.

No changes since 6.5

Process Monitor API

The Process Monitor API lets you see information about ongoing processes, messages associated with them, and a day-by-day history of long running processes (large ingests). It is most useful for tracking OPEX ingests, but normal ingests also create a Process which you can watch with this API. This API exposes the same information available through the Monitor webapp, or the Notifications panel on SDB and Explorer, if you have those enabled.

See this article for more information about monitoring.

No changes since 6.5

Report API

The Report API allows you to retrieve and run reports. Like the Entity API, it has a progress endpoint to allow you to track long running reports, and an /actions/reports endpoint to see running or completed reports.

No changes since 6.5

Administration and Management API

This API allows you to perform some administrative and management tasks, which you'd normally do through the Administration menu in the main application. Endpoints on this API typically require Manager or Admin role.

Changes since 6.5

• When creating a new user account with POST to /users, you may now specify a "source" parameter which affects the welcome email.
• If you have the temporary users feature enabled, the management endpoints under /temporary-users have been added to create, delete and manage temporary users. Temporary users allow credentials to be created which can be used to acquire API access tokens (not log in to the UI) for a limited period.

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.

No changes since 6.5

Storage API

You can use this API to discover your storage quota limit. This is currently only relevant in the context of Preservica Starter.

No changes since 6.5

Security API

This API provides security information visible for the current user. (Security configuration is done through the /security section of the Admin API).

No changes since 6.5

PAR (Registry) API

This API is for getting information from the Preservica Registry, and updating it if you have institution specific preservation needs. You need Registry Admin role to make any updates (which, on our hosted systems, is only available to Preservica staff). See this blog post on PAR for more information about PAR and how to use this API. Note that this API is on the Registry webapp (on the application server), not on the API webapp.

Changes since 6.5

• There are no structural changes to the API endpoints. However, we have updated most migration rules (business actions) to include the expected output formats, to help automated 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 6.5

• Migration settings can now be updated via PUT, POST and DELETE endpoints under /migration/config.

Location API

This API provides information about locations (also known as sources) configured in Preservica. Currently it only offers information about upload locations (i.e. ingest sources). Use this API if you need to upload content into Preservica which is too large or inconvenient to send to ingest endpoints on the Entity API.

No changes since 6.5

OAI-PMH

OAI-PMH is a standard protocol through which archival systems can exchange information. Preservica exposes data as an OAI-PMH data provider through the /OAI-PMH route. This API is described in the SDK: Content API document.

The main use of OAI-PMH is to list recently changed records. If you aren't integrating with an OAI-PMH consumer, consider using /entities/updated-since on the Entity API.

No changes since 6.5

CMIS

CMIS is a standard protocol through with content management systems can exchange information. Preservica exposes a limited subset of data through a read only CMIS 1.1 endpoint at /api/cmis/atom. (You can't use CMIS to create or update entities in Preservica.) The information available through CMIS is similar to that exposed by the Content API endpoints for top level entity listing, object details, searches and object children. Like the Content API, the information returned in the CMIS Metadata extension is generated from the relevant descriptive metadata fragments through their CMIS transform (e.g. a MODS to CMIS transform if you have MODS metadata).

The Content API is more widely used and more robust so consider using that if you aren't integrating with a CMIS consumer.

No changes since 6.5