-
Notifications
You must be signed in to change notification settings - Fork 13
Getting Started Guide
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.ymlfile 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.ymllooks like this, with the URL for the ArchivesSpace backend (API) asbaseurland theusernameandpasswordfor a User with API access.baseurl: http://localhost:8089 username: admin password: admin
- For OS X and Linux this is usually
.yml files optionally might also have more advanced configuration, such as logging.
For more detail, consult the README
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. All the further examples on this page assume that you've already done this.
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
# change '2' to any repository ID
repo = aspace.repositories(2)
print (repo.name)
>> My Awesome ArchivesSpace Repositoryfor 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 Recordsrepo = aspace.repositories(2)
# change '1' to any resource :id
collection = repo.resources(1)
print (collection.title)
>> Murder Victims' Families for Reconciliation Recordsrepo = aspace.repositories(2)
# change '1' to any archival_object :id
ao = repo.archival_objects(1)
print(file.title)
>> Minutesrepo = aspace.repositories(2)
# change '1' to any accession :id
transfer = repo.accessions(155)
print (transfer.accession_date)
>> 2018-06-20repo = 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.
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"
>> },
>> # ...repo = aspace.repositories(2)
collection = repo.resources(1)
myJSON = collection.json()
print (myJSON['uri'])
>> /repositories/2/resources/1repo = 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
>> # ...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, Undatedrepo = 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": []
>> }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",
>> # ...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
>> # ...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/26792Remember, 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].
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"
>> }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-1995repo = 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"
>> }
>> # ...The ArchivesSpace interface is currently read-only. If you need to update a record, you will need to drop down to the low-level API, ASpaceClient. For more information see Using ASpace().client() for Additional Endpoints.
In order to update a record or perform another type of action currently not supported by the abstraction layer, you can make an API call using ASpace().client.
You can access the ASpace client like so:
aspace.client.get('/repositories/2/resources/1')