Working with the ArchivesSpace API

ArchivesSpace features a powerful RESTful API that we use for multiple purposes, including the batch DAO workflow. Once you understand the basics of the API, you can use it to programmatically retrieve any data you need from an ArchivesSpace repository. For more complicated data wrangling tasks, it's often easier to use the API than to query the database directly.

Authentication

Not all API calls require authentication, but most of them do, so it's generally a good idea to authenticate before you get started. The authentication endpoint looks like this: http://your.archivesspace.instance:8089/users/admin/login

Note the use of port 8089, which is used for all API calls.

To authenticate, send a POST request to the authentication endpoint, passing the admin password for the ArchivesSpace instance as form data. You can use any HTTP library to do this. Here's what it would look like in curl if you were running ASpace locally and your password were 'admin':

curl -F password="admin" "http://localhost:8089/users/admin/login"

That will return a JSON response like this:

{"session":"6798221c0bcb9cd5f2ec705fa02b7aa4a3d1a5a440c79d1ad67774752a3b8a08","user":{"lock_version":211,"username":"admin","name":"Administrator","is_system_user":true,"create_time":"2017-06-02T20:20:05Z","system_mtime":"2018-03-21T15:29:03Z","user_mtime":"2018-03-21T15:29:03Z","jsonmodel_type":"user","groups":[],"is_admin":true,"uri":"/users/1","agent_record":{"ref":"/agents/people/1"},"permissions":{"/repositories/1":["update_location_record","delete_vocabulary_record","update_subject_record","delete_subject_record","update_agent_record","delete_agent_record","update_vocabulary_record","merge_subject_record","merge_agent_record","update_container_profile_record","update_location_profile_record","system_config","administer_system","manage_users","become_user","view_all_records","create_repository","delete_repository","transfer_repository","index_system","manage_repository","update_accession_record","update_resource_record","update_digital_object_record","update_event_record","delete_event_record","suppress_archival_record","transfer_archival_record","delete_archival_record","view_suppressed","view_repository","update_classification_record","delete_classification_record","mediate_edits","import_records","cancel_importer_job","manage_subject_record","manage_agent_record","manage_vocabulary_record","merge_agents_and_subjects","merge_archival_record","manage_rde_templates","update_container_record","manage_container_record","manage_container_profile_record","manage_location_profile_record","create_job","cancel_job","update_assessment_record","delete_assessment_record","manage_assessment_attributes"],"_archivesspace":["system_config","administer_system","manage_users","become_user","view_all_records","create_repository","delete_repository","transfer_repository","index_system","manage_repository","update_accession_record","update_resource_record","update_digital_object_record","update_event_record","delete_event_record","suppress_archival_record","transfer_archival_record","delete_archival_record","view_suppressed","view_repository","update_classification_record","delete_classification_record","mediate_edits","import_records","cancel_importer_job","manage_subject_record","manage_agent_record","manage_vocabulary_record","merge_agents_and_subjects","merge_archival_record","manage_rde_templates","update_container_record","manage_container_record","manage_container_profile_record","manage_location_profile_record","create_job","cancel_job","update_assessment_record","delete_assessment_record","manage_assessment_attributes","update_location_record","delete_vocabulary_record","update_subject_record","delete_subject_record","update_agent_record","delete_agent_record","update_vocabulary_record","merge_subject_record","merge_agent_record","update_container_profile_record","update_location_profile_record"]}}}

The only thing we care about here is the session ID -- that long string at the beginning. You'll need that later, so save it to a variable. Again, using Bash:

SESSION=6798221c0bcb9cd5f2ec705fa02b7aa4a3d1a5a440c79d1ad67774752a3b8a08

Making API Calls

Note: Though the examples in this section are all GET requests, the ASpace API supports full CRUD operations. The reference guide includes all of the endpoints and should be your first stop when you use the API.

Calling the ASpace API is just a matter of sending an HTTP request with the session ID in the headers. Generally, the endpoint format for GET requests looks like this: http://your.archivesspace.instance:8089/repositories/:repo_id/:record_type/:record_id

For example, here's how you would retrieve an accession:

curl -H "X-ArchivesSpace-Session: $SESSION" "http://localhost:8089/repositories/1/accessions/1

You can use the same method to get other record types, e.g.:

curl -H "X-ArchivesSpace-Session: $SESSION" "http://localhost:8089/repositories/1/resources/1
curl -H "X-ArchivesSpace-Session: $SESSION" "http://localhost:8089/repositories/1/digital_objects/1
curl -H "X-ArchivesSpace-Session: $SESSION" "http://localhost:8089/repositories/1/top_containers/1

All ArchivesSpace API calls return JSON, which can be parsed with relative ease. (There are libraries in Python and Ruby, to name a couple).

Examples

See https://github.com/BCDigLib/bc-aspace/tree/master/api-examples.

Reference

• ArchivesSpace API Reference: official API documentation that lists all of the endpoints.