API Design

Hierarchy of data

Project data follows a standard archival hierarchy: archives contain collections which contain documents which have content.

   graph LR
   archive-->collection;
   collection-->document;
   document-->content;

Loading

API entities and filter properties

Linked Data generally consists of Entities which are linked through Relationships. Archive, Collections, and Documents are specific entity types related to the process of organising archived documents. The remainder of the entities in the data fall into four broad categories: Agent (person or organisation), Location (physical or virtual), Event, Object.

Every entity has the following properties:

• Identifier (unique)
• Name
• Entity Type (one of Archive, Collection, Document, Agent, Location, Event, Object)
• Sub Type (derived from relationships in linked data)

Additionally, Locations and Events are complex objects having extra properties. Locations may have geographical coordinates, and events are associated with date ranges.

The table summarises the properties.

Entity	Properties
Agent	name, subtype
Place	name, subtype, coordinates
Event	name, subtype, from date, to date
Object	name, subtype

Entities also have relationships between each other. Archives, Collections, and Documents have an implicit relationship between each other, but each of them also have relationships to Agents, Locations, Events and Objects. In turn, Agents have relations to Locations, Events and Objects, and other Agents. The intention of the API is not to surface deep relationships (for example, tracing family trees) so will not provide the facility for recursive query definitions.

Some examples of Entity-Entity relationships are shown in the following table:

.	Agent	Place	Event	Object
Agent	Name	Place of residence	Date of birth	Medal
Place	Mayor	Name	Founded	Statue
Event	Involved	Happened at	Name	x
Object	Belonged to	Made at	Sold	Name

Example queries and response types

Q1. Which archives uploaded new records last week?

• Select Entities of type Document
• Select those with Event name = 'Created' and Date during last week
• Find archives those Documents are held in
• Return unique list of Ids and names of archives