Linked Data Registry REST Services
From v6 onwards, the preservation actions such as technical property extraction, validation and migration that Preservica performs has been controlled using a PAR data model (v0.3, described at https://github.com/JiscSD/rdss-par), rather than the MigrationPathways, Tools, ToolPurposes etc. of the Linked Data Registry model. Preservica also implements a v0.3 PAR API, to expose this data.
You can find Swagger UI for this API at https://demo.preservica.com/Registry/par/documentation.html.
The Linked Data Registry provides access to and control of the data contained via RESTful web services. These may be used to create, modify and delete any resource stored in the registry (provided the user has the necessary permission).
In this section, it will be assumed that the Linked Data Registry has been deployed on a server at http://server:8080/Registry/, this should be substituted with the actual deployment location of LDR in the URLs given.
CRUD Operations on Registry Resources
Basic CRUD operations on Registry entries may be performed from the root URL http://server:8080/Registry/rest/entityName, where entityName is replaced with the name of the entity to be accessed (e.g. fileFormat, internalSignature etc).
GET
The GET request provides Read functionality, returning data either in the XML schema required by Preservica, or one of a number of RDF representations (listed below).
Unless the session is already authenticated via JOSSO, a Basic Authentication header must be included with a valid username/password pair, otherwise a 401 Unauthorised error will result.
A GET request sent to a URL of the form http://server:8080/Registry/rest/entityName/entityPUID with a valid Authentication header but no other headers will return the requested resource in Preservica XML format. For example, a request to http://server:8080/Registry/rest/software/x-sfw/1 on a standard registry deployment will return:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SoftwareList xmlns="http://www.tessella.com/XIP/v4">
<software>
<name>Word</name>
<puid>x-sfw/1</puid>
<version>97 (8.0) for Windows</version>
<description>No description available</description>
<releaseDate>1997-01-01Z</releaseDate>
<vendor>Microsoft Corporation</vendor>
<website>www.microsoft.com/</website>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</software>
</SoftwareList>
The amount and format of information returned can be modified using a number of request headers, as detailed below:
| Option | Description |
|---|---|
| Accept | Defines the data type which is required as a response. Recognised values are: application/xml (default) and application/rdf |
| Format | When Accept is set to application/rdf, this defines the format in which the RDF triples willbe returned. Acceptable values are: RDF/XML (default), RDF/XML-A, RDF/JSON, N-TRIPLE, TURTLE, N3 |
| ResourceCreatedBy | Defines the registry resource prefix of the resource to be returned. If this is not provided,a search will be performed on the PUID alone. Providing the resource prefix makes the search more efficient but is not necessary in the majority of cases. |
| ReturnSubEntities | This boolean flag determines if any sub-resources (i.e., internal signatures, related file formats, tools, etc) should be fetched or not. The default is true. If this is set to false then only the minimum information required to identify the sub-resources will be returned (i.e. PUIDs and creating organisations). |
POST
A POST request creates a new entity in the registry. It may be used to create any resource type which is stored, including those which cannot currently be created from the GUI, such as Migration Pathway Role and Tool Purpose.
To insert a new resource into the registry, send a POST request to http://server:8080/Registry/rest/entityName with header Content-Type and Format set to describe the data format being provided, and the data itself in the request body.
Note that a PUID should not be included in the uploaded data, the system will generate a new PUID automatically to avoid clashes. To update an existing resource, see section PUT.
PUT
Update functionality is provided using PUT requests. The process is similar to creating a new entity above, except that the URL includes the PUID (e.g. http://server:8080/Registry/rest/software/x-fmt/1) and a PUT request is used. Note that any tags omitted from the data passed to the PUT request will be removed from
the resource. To avoid this happening accidentally, it is often useful to first issue a GET request on the same URL to determine what is currently held, edit this XML and PUT it back to the server.
For example, if we wish to update the Software resource referring to Word for Windows 6.0, we could first issue a GET request to the URL http://server:8080/Registry/rest/software/x-fmt/11, returning the following XML:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SoftwareList xmlns="http://www.tessella.com/XIP/v4">
<software>
<name>Word</name>
<puid>x-sfw/11</puid>
<version>6.0 for Windows</version>
<description>No description available</description>
<releaseDate>1993-11-03Z</releaseDate>
<withdrawnDate>2001-12-01Z</withdrawnDate>
<vendor>Microsoft Corporation</vendor>
<website>www.microsoft.com/</website>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</software>
</SoftwareList>
Perhaps we extend the name slightly and supply a short description:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SoftwareList xmlns="http://www.tessella.com/XIP/v4">
<software>
<name>Microsoft Word for Windows</name>
<puid>x-sfw/11</puid>
<version>6.0 for Windows</version>
<description>Version 6 of the popular Word processor</description>
<releaseDate>1993-11-03Z</releaseDate>
<withdrawnDate>2001-12-01Z</withdrawnDate>
<vendor>Microsoft Corporation</vendor>
<website>www.microsoft.com/</website>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</software>
</SoftwareList>
This XML is now ready to be returned to the server in the body of a PUT request to the same URL as before, http://server:8080/Registry/rest/software/x-fmt/11.
As in other requests, the response shows what has been stored in the registry.
When adding or altering a link to another resource, only the PUID and puidMintedBy tags need to be included to allow the link to be created, for example the following is the XML representation of internal signature is/100:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<InternalSignatures xmlns="http://www.tessella.com/XIP/v4">
<internalSignature>
<puid>is/100</puid>
<name>Drawing Interchange File Format 1.2</name>
<note>Header section with $ACADVER group code, EOF marker</note>
<byteSequence>
<puid>bs/47</puid>
<position>Variable</position>
<offset>0</offset>
<maxOffset>0</maxOffset>
<sequenceString>300D0A53454354494F4E0D0A2020320D0A4845414445520D0A*390D0A24414341445645520D0A2020310D0A4143312E320D0A*sequenceString>
<byteOrder>
</byteOrder>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</byteSequence>
<byteSequence>
<puid>bs/48</puid>
<position>Absolute from EOF</position>
<offset>0</offset>
<maxOffset>0</maxOffset>
<sequenceString>300D0A454F460D0A</sequenceString>
<byteOrder>
</byteOrder>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</byteSequence>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</internalSignature>
</InternalSignatures>
In order to add an extra byte sequence to the signature, we don’t need to know the full details of the sequence to add, only its puid and puidMintedBy properties, so we can add byte sequence bs/49 by editing the XML to:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<InternalSignatures xmlns="http://www.tessella.com/XIP/v4">
<internalSignature>
<puid>is/100</puid>
<name>Drawing Interchange File Format 1.2</name>
<note>Header section with $ACADVER group code, EOF marker</note>
<byteSequence>
<puid>bs/47</puid>
<position>Variable</position>
<offset>0</offset>
<maxOffset>0</maxOffset>
<sequenceString>300D0A53454354494F4E0D0A2020320D0A4845414445520D0A*390D0A24414341445645520D0A2020310D0A4143312E320D0A*sequenceString>
<byteOrder>
</byteOrder>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</byteSequence>
<byteSequence>
<puid>bs/48</puid>
<position>Absolute from EOF</position>
<offset>0</offset>
<maxOffset>0</maxOffset>
<sequenceString>300D0A454F460D0A</sequenceString>
<byteOrder>
</byteOrder>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</byteSequence>
<byteSequence>
<puid>bs/49</puid>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</byteSequence>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</internalSignature>
</InternalSignatures>
and returning it to the server in the body of a PUT request to http://server:8080/Registry/rest/internalSignature/is/100. This is true for any linked reference (Note: this is an example only and is not recommended since bs/49 does not relate to is/100).
DELETE
Deleting a resource can currently only be achieved through the REST interface. A DELETE request must include the ResourceCreatedBy header to avoid any ambiguity about which resource is to be deleted. Note: deletion cannot be undone.
Examples
Creating Tool Purposes
A tool purpose resource defines an operation which a given tool may perform on a given file format. For example, the DROID tool has over 800 tool Purpose objects which define its ability to identify the majority of file formats.
Currently ToolPurpose resources cannot be created via the Registry GUI, making it necessary to create them via the REST interface if additional ones are required (eg to use a new tool or have an old tool operate on a new format).
Creating a new tool purpose can easily be achieved by editing the following XML and then posting it to http://server:8080/Registry/rest/toolPurpose/ with Content-Type: application/xml and a valid authentication header.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ToolPurposes xmlns="http://www.tessella.com/XIP/v4">
<toolPurpose>
<priority>100</priority>
<purpose>Identification</purpose>
<appliesToFormat>
<puid>x-fmt/2</puid>
<puidMintedBy>http://www.nationalarchives.gov.uk</puidMintedBy>
</appliesToFormat>
</toolPurpose>
</ToolPurposes>
Preservica on Github
Open API library and latest developments on GitHub
Visit the Preservica GitHub page for our extensive API library, sample code, our latest open developments and more.
Preservica.com
Protecting the world’s digital memory
The world's cultural, economic, social and political memory is at risk. Preservica's mission is to protect it.