Skip to main content

The ArchivesSpace API

This article is meant to address some of the practical concerns in getting started with the ArchivesSpace Application Programming Interface (API) on your Atlas-hosted server.

info

For a comprehensive introduction to the ASpace API, please consider watching the in-depth Introduction to the ArchivesSpace API presentation and demonstration (3 hours, 47 minutes) and referencing the related article The ArchivesSpace API Playbook.

One interface of many​

There are multiple interfaces in the ArchivesSpace application:

  1. The Staff User Interface (SUI)
  2. The Public User Interface (PUI)
  3. The Application Programming Interface (API)
  4. The Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) Interface

This article is scoped only to the ArchivesSpace API.

Why the API?​

The main uses of the ArchivesSpace API are:

  • Application interoperability/integration
  • Large-scale, programmatic data cleanup or changes to your ArchivesSpace data made via scripts
  • Data ingest via script
  • Data harvesting
  • Reporting

No matter the reason for your interest, the following sections usually apply when getting started with this interface.

Enabling the API​

ArchivesSpace comes with an API by default the same way it comes with a Staff Interface and a Public User Interface. However, Atlas Systems will not turn on your API until it is requested. Whether or not to enable the API is one of the questions asked during the server build process at Atlas, but if you are unsure whether your API is on or off, please submit a support ticket to inquire.

The following phrases are synonymous but are provided because documentation refers to this action in different ways:

  • turning on the API
  • opening the API
  • enabling the API
  • configuring the API

All of these phrases refer to the same action and mean the same thing.

Atlas Systems controls whether or not your API is on or off by configuring a port on your server(s). This process is very easy and just requires a support ticket submitted to support@atlas-sys.com by one of your site's primary or secondary security contacts . Atlas will then enable your API with a simple server restart (which can happen overnight).

The API is accessed via URL​

Interacting with the API is beyond the scope of this article, but the short explanation is that the API is accessed via a URL and that you interact with that URL via the command line, a script (like a Python script), or a graphical user interface used for accessing APIs, such as Postman.

When enabling the API, Atlas creates a new URL that is specific to your server. As an example, the URL of the ArchivesSpace Sandbox API is https://sandbox.archivesspace.org/staff/api/. Your specific URL is the address against which you send requests and receive data back from.

If you click on that link, all you see is a brief statement that is not useful to you, but, seeing this statement shows us that the API is active and available via that URL.

Pro-tip: While most ASpace data is only available by authenticating to the API, there is one exception: https://sandbox.archivesspace.org/staff/api/repositories actually returns information about the repositories in the ArchivesSpace Sandbox without logging in. That is because this information is considered publicly available. Please read the next section about how to prevent public access to your API's URL.

Restricting access via IP address​

Clicking on https://sandbox.archivesspace.org/staff/api/repositories shows us that anyone with an internet connection can see an API unless it is IP restricted. Note that this does not mean anyone can log in; you still need a username and password and permissions to actually access any data that isn't repository data. But, the API itself is publicly available on the web.

For increased security, we recommend restricting access to the API URL to specific IP addresses or a range of addresses. To that end, we will ask that you list all IP addresses that should have access to your ArchivesSpace API when we configure it for you. This is information that should be available from your institution's IT provider.

Authenticating to the API​

Authenticating (i.e. logging in) to the API is the first crucial step after enabling it. Access to the ArchivesSpace API is through local ArchivesSpace user accounts.

A local account means an account created and managed inside ArchivesSpace itself and created in the staff user interface just the same as if you were on-boarding a new staff member and setting them up in ArchivesSpace for the first time.

  • The ASpace API does not offer SSO/OAuth authentication; instead, users use a local ArchivesSpace account to authenticate.
    • If you already use OAuth to log into the ArchivesSpace staff interface, you will not be using that same account to access the API. You will need to create a separate local account (i.e. an account within ArchivesSpace itself) to gain access to the API.
  • The ASpace API does not issue API tokens or passwords; instead, users use a local ArchivesSpace account to log in. The API does return a session key to users who do log in, but it is unique to the session and is ephemeral.
  • The session key expires based on the session time set in your config. If your session time is 60 minutes, the API session key will last 60 minutes before expiring. Re-authenticating refreshes the key. To change your session time configuration, please submit a support request to Atlas with your desired session time, in seconds. Ex. 60 minutes is 3600 seconds.

Step 1: Create a dedicated user account with a complex password​

A dedicated user account is not required for access to the API, but it is highly recommended.

  • If you are making changes to your data, having a dedicated account allows you to audit the API's actions (for example, you'll see that the last change made to a record was made via the API and not by a staff member account) and most importantly, you can control that account's permissions.
  • If you are granting access to your data to another application, having a dedicated account allows you to control that account's permissions at a granular level, including limiting or granting access to certain repositories or record types.

Access to the ArchivesSpace API is via a local staff account and this account is created exactly as if you were on-boarding a new employee and creating an account for them.

In our example, we will give the username api_user to an account:

Creating a dedicated API user account

Though it is universal advice, Atlas encourages that the password you select for your dedicated API account (or any account) should be complex. There are password generators like this one to assist in creating secure passwords.

warning

Note: Atlas submitted a bug report that the API does not escape ampersands, percent signs, or semi-colons in passwords when authenticating. Please refer to the status of that bug by clicking the link.

Step 2: Grant that account permissions​

Give your dedicated API account read-ONLY (or view-only) permissions in every repository where you want the account to have access (if you have more than one):

Setting API user permissions

Important considerations​

The API is a powerful tool. Its massive potential is what makes it so worthwhile to learn and leverage, but, it must be stated that the API is as potentially dangerous as it is useful. This section lays out points of caution that highlight ways to protect your data when using the ASpace API.

Read-Only should be the default​

In the Authenticating to the API section of this article there are instructions for creating a dedicated user account for the use of the ArchivesSpace API. Atlas recommends that that account be limited to only Read/View permissions by default. Edit/Write or Delete permissions should only be granted upon identifying a real and vital need. Essentially, do not grant editing or deleting permissions until you absolutely need to, and if you're working on a finite project, remember to go back and remove the edit and/or delete privileges once the project is complete.

Do not test changes against Production data​

If you are using your API access to facilitate data cleanup or other changes to your data, there is no more universal warning than to not use your actual Production server when learning and testing the API, especially if you are using an account that has Edit or Delete permissions.

Alternatives to using Production are:

  1. Enterprise customers are encouraged to use their Atlas-hosted Sandbox server for API testing. If you are not already an Enterprise customer but wish to become serious about using the ASpace API, it is prudent to consider a hosted sandbox that mimics your Production server and its data and settings. If you'd like to upgrade your hosting service to include a sandbox, please connect with us.
  2. If you cannot host a Sandbox with us, you can use "the" ArchivesSpace Sandbox (username/password = admin/admin), which has its API available at https://sandbox.archivesspace.org/staff/api/. That API is available to test against.
  3. If you have the technical skills to launch your own local test server, meaning that you can launch an instance of ArchivesSpace on your own computer, you can always request a copy of your Atlas-hosted data to load into that local sandbox's MySQL database so that you can test against your own data locally.

Request special backups​

While Atlas backs up your server(s) daily, you are welcome to request an special backup immediately before beginning an API project. Please email us at support@atlas-sys.com to request a special back up.

Additional Resources​

For a comprehensive introduction to the ASpace API, please consider watching the in-depth Introduction to the ArchivesSpace API presentation and demonstration (3 hours, 47 minutes) and referencing the related article The ArchivesSpace API Playbook.

The official API documentation is available here.