Skip to content

Getting Started Guide

Jump to bottom
William David Mayo ("Dave") edited this page Aug 8, 2018 · 11 revisions

Setup Credentials

In order to use the ArchivesSpace API, you need to have credentials for a user with API access (and the appropriate permissions to interact with any records you want to view/alter). ArchivesSnake knows and will default to the credentials for the test/development database. You can also provide credentials in a configuration file, with the simplest method being:

  • Make a .archivessnake.yml file in your home directory
    • For OS X and Linux this is usually /home/[my user name]/.archivessnake.yml
    • For Windows, its usually C:\Users\[my user name]\.archivessnake.yml
    • A basic .archivessnake.yml looks like this, with the URL for the ArchivesSpace backend (API) as baseurl and theusername and password for a User with API access. 
      baseurl: http://localhost:8089
username: admin
password: admin

.yml files optionally might also have more advanced configuration, such as logging. For more detail, consult the README

Setup a Script and Repositories

Importing and Initializing

from asnake.aspace import ASpace

aspace = ASpace()

# you can do things with ArchivesSpace now!

You'll need to do this at the top of any script or the beginning of any console session where you want to use ArchivesSnake.

An ASpace object represents the ASpace API in a convenient, read-only fashion. It will likely be the default way you will use ArchivesSnake to get records. If you need to POST or DELETE records or use API routes which aren't available or supported by the abstraction layer, you can make any API call with ASpace().client, such as ASpace().client.get('/repositories/2/my_endpoint').

Right now, the abstraction layer is incomplete and read-only, but soon we hope it will cover most basic uses. It might take awhile for some endpoints to be included, and some might not ever be; but the client layer can handle any API route

For more detail, consult the README

Getting a single Repository

# change '2' to any repository ID
repo = aspace.repositories(2)
print (repo.title)

>> My Awesome ArchivesSpace Repository

Looping through multiple repositories

for repo in aspace.repositories:
	print(repo.name)
	print(repo.resource(1).title)
	
>> "My Awesome ArchivesSpace Repository
>> A Unique Group of Useful Records
>> M.E. Grenander Department of Special Collections & Archives
>> Murder Victims' Families for Reconciliation Records

The Basics

Getting Resources

repo = aspace.repositories(2)

# change '1' to any resource :id
collection = repo.resources(1)
print (collection.title)

>> Murder Victims' Families for Reconciliation Records

Getting Archival Objects

repo = aspace.repositories(2)

# change '1' to any archival_object :id
ao = repo.archival_objects(1)
print(file.title)

>> Minutes

How about Accessions?

repo = aspace.repositories(2)

# change '1' to any accession :id
transfer = repo.accessions(155)
print (transfer.accession_date)

>> 2018-06-20

I have something, what do I do with it?

List available methods on an object

repo = aspace.repositories(2)

collection = repo.resources(1)
print(dir(collection))

>> ['_client', '_json', 'classifications', 'create_time', 'created_by', 'dates', 'deaccessions', 'ead_id', 'ead_location', 'extents', 'external_documents', 'external_ids', 'finding_aid_author', 'finding_aid_date', 'finding_aid_language', 'finding_aid_sponsor', 'finding_aid_status', 'finding_aid_title', 'id_0', 'instances', 'is_ref', 'jsonmodel_type', 'language', 'last_modified_by', 'level', 'linked_agents', 'linked_events', 'lock_version', 'notes', 'publish', 'related_accessions', 'repository', 'restrictions', 'revision_statements', 'rights_statements', 'subjects', 'suppressed', 'system_mtime', 'title', 'tree', 'uri', 'user_mtime']

Note: This is not a comprehensive list - this should show all the properties of the object that are directly in the object's JSON, but won't show descendant API routes.

Just Print() it to Pretty Print the JSON

repo = aspace.repositories(2)

collection = repo.resources(1)
print(collection)

>> {
>>   "lock_version": 3,
>>   "title": "Murder Victims' Families for Reconciliation Records",
>>   "publish": true,
>>   "restrictions": false,
>>   "ead_id": "apap313",
>>   "ead_location": "http://meg.library.albany.edu:8080/archive/view?docId=apap313.xml",
>>   "finding_aid_title": "Murder Victims Families for Reconciliation; Records",
>>   "finding_aid_date": "2015",
>>   "finding_aid_author": "Samantha Brown",
>>   "finding_aid_language": "English",
>>   "finding_aid_sponsor": "This project was made possible by a grant from the Council on Library and Information Resources (CLIR)",
>>   "created_by": "greg",
>>   "last_modified_by": "robotimporter",
>>   "create_time": "2017-04-05T20:04:07Z",
>>   "system_mtime": "2017-05-04T13:45:17Z",
>>   "user_mtime": "2017-04-06T19:40:15Z",
>>   "suppressed": false,
>>   "id_0": "apap313",
>>   "language": "eng",
>>   "level": "collection",
>>   "finding_aid_status": "new",
>>   "jsonmodel_type": "resource",
>>   "external_ids": [],
>>   "subjects": [
>>     {
>>       "ref": "/subjects/91"
>>     },
>>     {
>>       "ref": "/subjects/1029"
>>     },
>>     {
>>       "ref": "/subjects/1030"
>>     },
>> # ...

Just Get the JSON

repo = aspace.repositories(2)

collection = repo.resources(1)
myJSON = collection.json()
print (myJSON['uri'])

>> /repositories/2/resources/1

Getting All The Things

Listing resources

repo = aspace.repositories(2)

for resource in repo.resources:
	print (resource.id_0 + ' ' + resource.title)

>> apap001 American Association of University Professors, Albany Chapter Records
>> apap002 American Association of University Women, Albany Branch Records
>> apap003 Association of Colleges and Universities of the State of New York (ACUSNY) Records
>> # ...

Listing Children of Resources

repo = aspace.repositories(2)
collection = repo.resources(231)

for child in collection.tree.children:
	print (child.level + " - " + child.title)

>> series - Administrative Files, 1977-2005, Undated
>> series - Correspondence, 1994-2005, Undated
>> series - Outreach and Publications, 1994-2004, Undated
>> series - Events, 1992-2003, Undated
>> series - Subject Files, 1981-2007, Undated

Children from Trees are not full archival objects

repo = aspace.repositories(2)
collection = repo.resources(231)

for child in collection.tree.children:
	print(child)
	
>> {
>>   "title": "Office of Equal Employment Opportunity , 1973 - 1974",
>>   "id": 223023,
>>   "record_uri": "/repositories/2/archival_objects/223023",
>>   "publish": true,
>>   "suppressed": false,
>>   "node_type": "archival_object",
>>   "level": "series",
>>   "instance_types": [],
>>   "containers": [],
>>   "has_children": false,
>>   "children": []
>> }

Get Full Archival Objects from Trees

from asnake.aspace import ASpace

repo = aspace.repositories(2)
collection = repo.resources(231)

for child in collection.tree.children:
	series = child.record
	print(series)
	
>> {
>>   "lock_version": 2,
>>   "position": 9,
>>   "publish": false,
>>   "ref_id": "03199a7f042cc5cc1a1da3e707e70759",
>>   "title": "Office of Diversity and Inclusion",
>>   "display_string": "Office of Diversity and Inclusion, 2015",
>>   "restrictions_apply": false,
>>   "created_by": "miles",
>>   "last_modified_by": "miles",
>>   "create_time": "2018-07-09T14:57:50Z",
>>   "system_mtime": "2018-07-26T13:45:24Z",
>>   "user_mtime": "2018-07-20T20:08:13Z",
>>   "suppressed": false,
>>   "level": "series",
>>   "jsonmodel_type": "archival_object",
>>   "external_ids": [],
>>   "subjects": [],
>>   "linked_events": [],
>>   "extents": [
>>     {
>>       "lock_version": 0,
>>       "number": "0.17",
>> # ...

Looping down the Hierarchy

repo = aspace.repositories(2)
collection = repo.resources(102)

for series in collection.tree.children:
	for folder in series.children:
		print (folder.title)
		
>> General Activism, 1975-2000, Undated
>> National Gay and Lesbian Task Force, 1985-1998, Undated
>> National March on Washington, 1993, 1987-1994, Undated
>> Seneca Women's Encampment for a Future of Peace and Justice (1983-1988), 1982-1991, Undated
>> # ...

Gotchas with Trees

Just remember, when you use .tree on a resource or an archival_object, you're getting part of a TreeObject which is different than a complete archival_object. Use .record when you need the full archival_object

repo = aspace.repositories(2)
collection = repo.resources(102)

for child in collection.tree.children:
    # child here is only a node of a tree object
    # tree nodes have things like .level, .id, .record_uri, .title, and .has_children
    if child.title == "General Activism":
        print (child.record_uri)

        series = child.record
        # series is the full archival_object
        # archival_objects have additional things like .uri, .dates, .extents, .subjects
        print (series.uri)
		
>> /repositories/2/archival_objects/26792
>> /repositories/2/archival_objects/26792

Dates and Extents

Remember, dates and extents are typically lists, so you want to make sure to loop though them or call them by index like resource.extents[0].

Dates

repo = aspace.repositories(2)
collection = repo.resources(102)

print(collection.dates[0].date_type)

>> inclusive

print(collection.dates[0].begin)

>> 1927

print(collection.dates[0].end)

>> 2000

print(collection.dates[0].expression)

>> 1927-2000

print(collection.dates[0])

>> {
>>   "lock_version": 0,
>>   "expression": "1927-2000",
>>   "begin": "1927",
>>   "end": "2000",
>>   "created_by": "greg",
>>   "last_modified_by": "greg",
>>   "create_time": "2017-08-08T21:11:46Z",
>>   "system_mtime": "2017-08-08T21:11:46Z",
>>   "user_mtime": "2017-08-08T21:11:46Z",
>>   "date_type": "inclusive",
>>   "label": "creation",
>>   "jsonmodel_type": "date"
>> }

Looping through Dates

from asnake.aspace import ASpace

repo = aspace.repositories(2)
collection = repo.resources(102)

for date in collection.dates:
	print(date.date_type + ": " + date.expression)
	
>> inclusive: 1927-2000
>> bulk: 1982-1995

Extents work the same way

repo = aspace.repositories(2)
collection = repo.resources(102)

print(collection.extents[0].number)

>> 44.4

for extent in collection.extents:
	print (extent)

>> {
>>   "lock_version": 0,
>>   "number": "44.4",
>>   "created_by": "greg",
>>   "last_modified_by": "greg",
>>   "create_time": "2017-08-08T21:11:46Z",
>>   "system_mtime": "2017-08-08T21:11:46Z",
>>   "user_mtime": "2017-08-08T21:11:46Z",
>>   "portion": "whole",
>>   "extent_type": "cubic ft.",
>>   "jsonmodel_type": "extent"
>> }
>> # ...

Updating Things

Using ASpace().client() for Additional Endpoints

Clone this wiki locally