Exploring Link → Direction ←

Subtitled: The Staff Interface may fool you

Exploring Link Direction: Agent records

http://localhost:8080/agents/agent_corporate_entity/101

You cannot see the records linked to → an agent or subject through the API like you can in the staff interface

You can only see the agents/subjects linked from ← those records

import requests
import json

baseURL = 'http://localhost:8089'
user = 'admin'
password = 'secure_password'
repository = '101'

auth = requests.post(baseURL + '/users/' + user + '/login?password=' + password).json()
session = auth['session']
headers = {'X-ArchivesSpace-Session': session, 'Content_Type': 'application/json'}

print('Your session key is: ' + session)

output = requests.get(baseURL + '/agents/corporate_entities/101', headers=headers).json()
print(json.dumps(output, indent=2))

This matters because if you're looking to use the API to create or change links between records you must change/create the link via the endpoint for the record from which the link originates

• So in this example, you can only change the link to the agent record ← from the descriptive record, like a resource record
• You cannot change the resources an agent links to from the agent record

Pro-tip: The easiest test for this is in the staff interface itself, which is usually a mirror for the API. When you look at an agent record in AS, you also cannot add resources on that screen, you can only add agents to resources on a resource record.

Exploring Link Direction: Top Containers and Instances

http://localhost:8080/top_containers/1

output = requests.get(baseURL + '/repositories/' + repository + '/top_containers/1', headers=headers).json()
print(json.dumps(output, indent=2))

So to reinforce the point:

You cannot see the records linked to → a top_container through the API like you can in the staff interface

You can only see the top containers linked from ← those records

Any discussion of linking and top containers is also a good moment to explore instances through the API. It's good to know that physical instance information in an AO lives in two places:

In Archival object records

The instance array, the instance type (mixed materials) and the child information (folder/item number) lives in the archival object. [:GET] /repositories/:repo_id/archival_objects/:id

And in Top container records

The top container type, indicator, and barcode live in the top container record. [:GET] /repositories/:repo_id/top_containers/:id

I want to demonstrate this using the very simple phase Box 1, Folder 4

One phrase, four pieces of information, two endpoints:

/repositories/:repo_id/archival_objects/:id

• Folder → type_2 in the sub_container array in the instance array
• 4 → → → indicator_2 in the sub_container array in the instance array

/repositories/:repo_id/top_containers/:id

• Box → → type
• 1 → → → indicator

So over the next few slides I am going to focus closely on the instances array in an archival object AND focus on a top container record.

And we're still exploring linking, so the other lesson here is that if you start on the top_container record, you will not find instance information, nor will you find a link to the AO to go fetch it.

Start from the archival object record, find the instance array, find the folder information and a link to the top container, then follow the link to the top container, grab the container info, and you will have completed your quest.

AO_output = requests.get(baseURL + '/repositories/' + repository + '/archival_objects/6', headers=headers).json()
print(json.dumps(AO_output['instances'], indent=2))

type_2 = AO_output['instances'][0]['sub_container']['type_2']

indicator_2 = AO_output['instances'][0]['sub_container']['indicator_2']

top_container_uri = AO_output['instances'][0]['sub_container']['top_container']['ref']

type_2 = AO_output['instances'][0]['sub_container']['type_2']
indicator_2 = AO_output['instances'][0]['sub_container']['indicator_2']

top_container_uri = AO_output['instances'][0]['sub_container']['top_container']['ref']

So those actions got us Folder and 4 and the info we need to go find the container.

Start from the archival object record, find the instance array, find the folder information and a link to the top container, then follow the link to the top container, grab the container info, and you will have completed your quest.

top_container_uri = AO_output['instances'][0]['sub_container']['top_container']['ref']

TC_output = requests.get(baseURL + top_container_uri, headers=headers).json()
print(json.dumps(TC_output, indent=2))

TC_output = requests.get(baseURL + top_container_uri, headers=headers).json()

TC_type = TC_output['type']

TC_indicator = TC_output['indicator']

To construct the box and folder number statement, you must start from the archival object record, find the instance array, find the folder information and a link to the top container, then follow the link to the top container, grab the container info, and you will have completed your quest.

AO_output = requests.get(baseURL + '/repositories/' + repository + '/archival_objects/6', headers=headers).json()

type_2 = AO_output['instances'][0]['sub_container']['type_2']

indicator_2 = AO_output['instances'][0]['sub_container']['indicator_2']

top_container_uri = AO_output['instances'][0]['sub_container']['top_container']['ref']

TC_output = requests.get(baseURL + top_container_uri, headers=headers).json()

TC_type = TC_output['type']

TC_indicator = TC_output['indicator']

AO_output = requests.get(baseURL + '/repositories/' + repository + '/archival_objects/6', headers=headers).json()

type_2 = AO_output['instances'][0]['sub_container']['type_2']

indicator_2 = AO_output['instances'][0]['sub_container']['indicator_2']

top_container_uri = AO_output['instances'][0]['sub_container']['top_container']['ref']

TC_output = requests.get(baseURL + top_container_uri, headers=headers).json()

TC_type = TC_output['type']

TC_indicator = TC_output['indicator']

print(TC_type + ' ' + TC_indicator + ', ' + type_2 + ' ' + indicator_2)

Gotchas:

• The interface can fool you on what you think is linked to what
  • Always test your assumptions in the API
• Links only exist in one place and only go one way
  • Important for wayfinding
  • Important for making changes
• Information that feels related can be stored in different records
  • Accessible via different endpoints

# This demonstration script is just a way to explore example GETs, it doesn't contain any POSTs
# However, this script does container examples of how to isolate elements in JSON via Python
# Final script all together.
# If you want to re-purpose this script, this is the block to use.
# Save it as name_of_file.py in order to run it as Python3 in your local environment.
# Disclaimer: This script is being provided as an example and may need to be modified for local use.
# Modifying and using this script is the responsibility of the individual using it.
# Do not test against Production!
# Authentication based on a script by ehanson8 (https://github.com/MITLibraries/archivesspace-api-python-scripts)

#Import the following libraries
import json
import requests

#Set your authentication info, baseurl, and repository info (if relevant)
baseURL = 'http://localhost:8089'
user = 'admin'
password = 'secure_password'
repository = '101'

#Authorize and store your session key in your header
auth = requests.post(baseURL + '/users/' + user + '/login?password=' + password).json()
session = auth['session']
headers = {'X-ArchivesSpace-Session': session, 'Content_Type': 'application/json'}

print('Your session key is: ' + session + ' for ' + baseURL)

# Print the container and child number for the physical instance in archival_objects/6:

# Start from the archival object record
AO_output = requests.get(baseURL + '/repositories/' + repository + '/archival_objects/6', headers=headers).json()

# find the instance array and the folder information
type_2 = AO_output['instances'][0]['sub_container']['type_2']

indicator_2 = AO_output['instances'][0]['sub_container']['indicator_2']

# find the instance array and a link to the top container
top_container_uri = AO_output['instances'][0]['sub_container']['top_container']['ref']

# follow the link to the top container
TC_output = requests.get(baseURL + top_container_uri, headers=headers).json()

# grab the container info
TC_type = TC_output['type']

TC_indicator = TC_output['indicator']

# and you will have completed your quest
print(TC_type + ' ' + TC_indicator + ', ' + type_2 + ' ' + indicator_2)