x19512 API

You can use the x19512 API to preserve, retrieve, and delete content with ETSI TS 119 512, the European standard protocol for long-term preservation services. A preservation object (PO) is a file or a metadata document. The POs that you preserve together become one package in the archive, and their POID is the package ID.

An x19512 call reports its outcome in the response body, not in the HTTP status. Most calls return 200 OK, also when the request fails, and the result object in the body tells you what happened.

The archive supports four operations of the standard: RetrieveInfo, PreservePO, RetrievePO, and DeletePO. UpdatePOC, RetrieveTrace, ValidateEvidence, and Search aren't available.

Each operation is a POST with a JSON body, under the path prefix /x19512/. Every call needs the headers in Common headers and an access token, as described in Authentication.

Required role: any valid access token, for every operation. Package permissions still apply. To preserve content, the account must be able to add content to the archive. To retrieve or delete a package, it needs access to that package.

Read the result of a call

Every response has a result object:

The major code is one of these:

• urn:oasis:names:tc:dss:1.0:resultmajor:Success: the call worked.

• urn:oasis:names:tc:dss:1.0:resultmajor:RequesterError: something in your request is wrong or not supported.

• urn:oasis:names:tc:dss:1.0:resultmajor:ResponderError: the archive couldn't handle the request.

• urn:oasis:names:tc:dss:1.0:resultmajor:InsufficientInformation: the call partly worked. RetrievePO uses it when it returns the files but not the evidence.

The minor codes are the URIs of the standard, such as http://uri.etsi.org/19512/error/unknownPOID. Each operation lists the ones that it can return.

When a call fails before it gets to the operation, for example because the token is missing or something unexpected went wrong, you get an HTTP error status with a {code, message} body instead. To handle these, go to Errors. If Docbyte turned the API off for your archive, every call gets a 500 error like this one.

{
  "code": "EXCEPTION",
  "message": "Internal server error. Error id: 0b7e3c55-1f4a-4d2e-9c8b-6a5f4e3d2c1b"
}

Get profile information

RetrieveInfo returns the details of a preservation profile: which operations it supports, and which formats each operation accepts and returns. Use it to find the format IDs to put in a PreservePO or RetrievePO request.

POST /x19512/RetrieveInfo

Body fields:

{
  "reqId": "req-0001",
  "pro": "urn:example:profiles:hr-records-1.0"
}

Response: 200 OK with the result, your reqId, and a pro list that holds the Profile.

Minor codes that you can get:

• http://uri.etsi.org/19512/error/notSupported: stat isn't active or all.

Preserve objects

You send one or more POs with PreservePO, and the archive makes one new package of them.

POST /x19512/PreservePO

Body fields:

Each PO's formatId decides what it becomes in the package:

• The namespace of a metadata schema that the archive knows, such as http://purl.org/dc/elements/1.1/ for Dublin Core: the PO becomes descriptive metadata of the package.

• A format that the profile accepts for PreservePO: the PO becomes a representation of the package, with the PO's id as its name.

If a formatId is both, the PO becomes metadata.

{
  "reqId": "req-0002",
  "pro": "urn:example:profiles:hr-records-1.0",
  "po": [
    {
      "id": "contract.pdf",
      "formatId": "http://uri.example.com/formats/pdf",
      "mimeType": "application/pdf",
      "binaryData": {
        "value": "JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFI+PgpzdHJlYW0K"
      }
    },
    {
      "id": "dc.xml",
      "formatId": "http://purl.org/dc/elements/1.1/",
      "mimeType": "application/xml",
      "binaryData": {
        "value": "PG1ldGFkYXRhPjxkYzp0aXRsZT5Db250cmFjdDwvZGM6dGl0bGU+PC9tZXRhZGF0YT4="
      }
    }
  ]
}

Response: 200 OK with the result, your reqId, and the poId of the new package.

{
  "reqId": "req-0002",
  "result": {
    "maj": "urn:oasis:names:tc:dss:1.0:resultmajor:Success"
  },
  "poId": "uuid-9d2f4b6a-3c1e-4a8b-b7d5-0e6f1a2c3b4d"
}

The call returns as soon as the archive has your content. The ingest continues in the background, and until it finishes, RetrievePO answers with unknownPOID.

Minor codes that you can get:

• http://uri.etsi.org/19512/error/parameterError: two POs have the same id.

• http://uri.etsi.org/19512/error/POFormatError: a PO's formatId isn't a known metadata schema and isn't a format that the profile accepts.

• http://uri.etsi.org/19512/error/internalError: the archive couldn't build the package.

Retrieve a preserved object

RetrievePO returns the files of a package, its evidence record, or both.

POST /x19512/RetrievePO

Body fields:

{
  "reqId": "req-0003",
  "poId": "uuid-9d2f4b6a-3c1e-4a8b-b7d5-0e6f1a2c3b4d",
  "sor": "POwithDetachedEvidence"
}

Response: 200 OK with the result, your reqId, and po: a list of PO objects.

• Each file has the id <representation name>/<index>, for example contract.pdf/0.

• The evidence record has the id metadata/preservation/evidence.4998.bin.

Minor codes that you can get:

• http://uri.etsi.org/19512/error/unknownPOID: there's no package with this poId, or its ingest hasn't finished yet.

• http://uri.etsi.org/19512/error/notSupported: sor is POwithEmbeddedEvidence or missing, or you sent a versionId.

• http://uri.etsi.org/19512/error/unknownPOFormat: the profile doesn't return poFormat.

• http://uri.etsi.org/19512/error/unknownEvidenceFormat: the profile doesn't have evFormat.

• http://uri.etsi.org/19512/error/parameterError, with the message Representation not found: a representation in optIn doesn't exist in the package.

• http://uri.etsi.org/19512/error/internalError, with the message Evidence not available: with sor set to Evidence, the package has no evidence record yet.

• http://uri.etsi.org/19512/warning/requestOnlyPartlySuccessful, with the major code InsufficientInformation and the message Evidence not available. Returning only POs: with POwithDetachedEvidence, you get the files, but the package has no evidence record yet.

Delete a preserved object

DeletePO deletes a package from the archive.

POST /x19512/DeletePO

Body fields:

{
  "reqId": "req-0004",
  "poId": "uuid-9d2f4b6a-3c1e-4a8b-b7d5-0e6f1a2c3b4d"
}

Response: 200 OK with the result and your reqId.

Minor codes that you can get:

• http://uri.etsi.org/19512/error/unknownPOID: there's no package with this poId.

• http://uri.etsi.org/19512/error/notSupported: mod is a mode other than SubDOsAndEvidence.

If the archive refuses to delete the package, you get an HTTP error with a {code, message} body instead.

Schemas

PO

A preservation object, in a request or a response.

Profile

The preservation profile, as RetrieveInfo returns it. The fields follow ETSI TS 119 512. These are the ones you need most:

Each parameter in in and out lists its formats in form. In each format, fid is the format ID, and def is true for the default. So the formats that PreservePO accepts are at op[].in[].form[].fid.