What's new in the 26.3 API

Release 26.3 adds new APIs to /v2, to manage packages, retention, package sets, preservation actions, and reports. It also brings a new error body and new roles. Some changes can affect an integration that works with 26.2, so check them first.

Changes that can affect your integration

• Create a user with POST /v2/user. PUT /v2/user doesn't exist anymore, and it gets a 405 error.

• GET /v2/user returns one page of users. Instead of an array, you get an object with items, page, pageSize, and total, and the page and pageSize parameters now work. Read the users from items, and ask for the next pages.

• GET /v2/url needs the archive-ingest role. Without it, the call gets a 403 error. If your client doesn't have the role, ask Docbyte.

• Use a metadata schema that the archive knows. A metadata schema namespace that the archive doesn't know gets a 400 error with the reason METADATA_SCHEMA_UNKNOWN.

• Don't store download links: they expire. By default, the url of each file in representations works for 24 hours. You call it with your access token in the Authorization header, and it points to /v2/content/{token} on the API. To get a new link, get the package again.

• Use schema names in the metadata enricher. The schema of each metadata section is now the schema name, such as dublincore, instead of the prefix, such as dc.

• GET /v2/aip/{packageId} checks the read permission. If your client can find a package but isn't allowed to read it, you get a 403 error with the reason DOCUMENT_ACCESS_DENIED.

• Check the new error code values if you switch on code. Every /v2 error now has code, reason, message, and errorId, and often params and details. Errors describes the body, and the tables after this list show what changed.

• Pick the tenant with the tenant header. X-Docbyte-Repository still works, but it's deprecated. Without either header, the archive now uses the tenant in your token. The tenant header is described in Common headers.

• A SIP from a URL must be on a public address. In PUT /v2/sip with the content type URL, the archive refuses local and internal network addresses.

Error codes that changed

Several errors that were a 500 now have a precise status and reason:

New APIs

• Archive API: manage one package. You can trash or restore it, change its permissions, or transfer it. You can also list the tenants that your client can work in.

• Audit trail API: search and export the audit trail of the archive or of one package.

• Retention API: manage retention rules, review deletion lists, and list legal holds.

• Package sets API: group packages into package sets, and share them.

• Preservation actions API: run preservation actions on packages, schedule them, and read their reports.

• Reports API: set up reports, run them, and get the results.

• Transformations API: set up file format transformations.

• Notifications API: set up notifications.

• Statistics API: get the content, storage, and submission statistics of the archive.

New in existing APIs

• Dissemination API: search with structured criteria, list the fields that you can search on, save search filters, export search results as CSV, and download files or stream them.

• Ingest API: list SIPs, remove a SIP, reingest a package, and get an upload URL with its key and expiry date. You can also give a metadata file its own name, so that one schema can have several metadata files.

• Admin API: search for users and groups, and list the archiving profiles.

Other improvements

• New roles: archive-content-manager, archive-records-manager, archive-records-reviewer, and archive-qa. Authentication says what each one allows.

• New enrichers: retentionstatus and evidence, described in Common headers.

• New package fields: a package now has a state and, after a QA review, a qaDecision. If your client rejects values that it doesn't know, allow new state values.

• More detail on failed ingests: a SIP and an ingest status now have failureReason and failureMessage when the ingest failed.

• New SIP fields: title, lastModified, lastContributor, and a filled status.

• Metadata validation errors: in an environment where the archive validates metadata documents, a document that doesn't match its schema gets a 400 error with the reason METADATA_INVALID, instead of a 500.

• Larger requests: by default, a request body can now be up to 21 MB.

• Downloads in parts: GET /v2/content/{token} supports the Range header, so you can resume a download.