Introduction

AtoM (Access to Memory) is an open-source web application for archive institutions. It is used by libraries, archives, and museums worldwide to manage archival descriptions.

AtoM operations are typically performed through the Web UI, but using the REST API enables integration with external systems and batch processing. In this article, we walk through the API following a realistic business scenario, confirming the results in the Web UI.

For details on the API plugin development history and implementation, see the separate article Developing a Plugin to Extend AtoM’s REST API.

APIs Used

  • arRestApiPlugin (AtoM standard): CRUD for Information Objects
  • arExtendedApiPlugin (custom developed): Operations for repositories, authority records, accessions, taxonomies, function descriptions, and digital objects

See the development article for a complete list of 28 endpoints.

Prerequisites

#e#exxApAptoPoorIrMttkUAeARTyPLOIM(_(_sKcUeEhRtYaL=n=i"g"nyehotAuatdrcpm-c:iao/npr/idl>-iokncSegaeylt-ththooiesnrytgeo:s"u6r3>0e0Gn1lv"oibraolnm>enAtP)Ikey)

The API key can be set and confirmed in AtoM’s admin screen (Settings > Global).

Business Scenario: “Building the Hashimoto City Library Digital Archive”

Story

Hashimoto City Library builds a digital archive of a historical photograph collection of Hashimoto City (Meiji to Showa periods) donated by local history researcher Hanako Yamada.

The following steps execute the series of tasks needed for archive construction using the API.

StepTaskAPI
0Check initial stateGET /api/summary
1Register repositoryPOST /api/repositories
2Verify repository informationGET /api/repositories/:slug
3Add contact informationPUT /api/repositories/:slug
4Register donorPOST /api/actors
5Verify donor informationGET /api/actors/:slug
6Create accession recordPOST /api/accessions
7Update processing statusPUT /api/accessions/:slug
8Check taxonomiesGET /api/taxonomies
9Add subject classificationPOST /api/taxonomies/:id/terms
10Correct classification namePUT /api/taxonomies/terms/:id
11Create archival descriptionPOST /api/informationobjects
12Attach digital imagePOST /api/informationobjects/:slug/digitalobject
13Check final stateGET /api/summary

After scenario completion, the “Additional Features” section also covers:

  • Function description (ISDF) management: POST /api/functions
  • Place taxonomy management: POST /api/taxonomies/42/terms
  • Hierarchical archival descriptions: POST /api/informationobjects (with parent_id)
  • Repository logo images: POST /api/repositories/:slug/logo

All curl commands below have been executed, and the responses are actual data.

Step 0: Check Initial State

First, check the number of records currently registered in AtoM.

cur$lAT-OsM_-UHRL"/RaEpSiT/-sAuPmIm-aKreyy:|$pAyPtIh_oKnE3Y"-m\json.tool
{}""""""iraatdnecceifptcrgoooemirsrsstmiss"aat"i:lto:o_irn3ooi0s2bne,"2j_s:,eo"cb:0tj,se1"c,:ts3":1,

Web UI confirmation: Top page

Step 1: Register Repository

Register Hashimoto City Library as an archive repository.

cur---}$lHHd'A"""""""""T-""'aiddhgmicOsRC{udeeieanoMEotesssontl_-SnhncctcdelUXTtot__ouareR-eridsrltncLPAnifetyteat/OPtzita"usliaSI-eeat:r"_npT-Tdriua:sgiKy_"ls"lt_/\epf:__橋_"rpryeoii本c図uoe::r"dd市o書clpmh""立n館tio$a_a::図t法ucsApos書eにriiPpfh22館x基eetIl_i33はtづsso_inm301"く""rKcao,,9:公::iEamt6共eYteo5"図""s"i"-年和書デ橋o:lに歌館ジ本\ni設山"タ市/"b立県,ルおj橋rさ橋アよs本aれ本ーびo市rた市カ周n立y公"イ辺"図"共,ブ地書,図室域\館書"の"館,歴,で史す資。料2、0古2文0書年、よ写り真歴資史料資を料収の集デ対ジ象タとルすアるー。カ"イブ事業を開始しました。",
{}""isdl"u:g"4:66",ayya-htm3-5wkd"

desc_detail_id and desc_status_id are taxonomy term IDs (explanation in Step 8).

Web UI confirmation: Repository list

Step 2: Verify Repository Information

Retrieve details of the created repository.

cur$lAT-OsM_-UHRL"/RaEpSiT/-rAePpIo-sKietyo:ri$eAsP/Ia_yKyEaY-"ht\m3-5wkd|python3-mjson.tool
{}""""""""""""""isiahmigcuddcudlduianeopeerp"uetsntollssed:gnhtdecloccaa"tooaruea__tt4:irrtnlcdsdee6fiyeatt_tedd6"iz"sluilat__,aee:"_rnitaaayrd:sagmuitty"_"tl_isl""a:f橋"r_pt""::-o本図uco"::h"r市書col:""thm立館tni""22ma_図法utc-FF003so書にrei1iu22-hf館基exe,nl665i_はづstsal--wmn1く"""l"00koa9公:::",22dtm6共,--"oe5図"""11,-"年書デ和橋55l:に館ジ歌本i設"タ山市00b"立,ル県お11r橋さア橋よ::a本れー本び33r市たカ市周34y立公イ"辺::"図共ブ,地35,書図室域60館書"の"""館,歴,,で史す資。料2、0古2文0書年、よ写り真歴資史料資を料収の集デ対ジ象タとルすアるー。カ"イ,ブ事業を開始しました。",

All fields specified in Step 1 are correctly registered.

Web UI confirmation: Repository detail page

Step 3: Add Contact Information

Add address, phone number, and other contact information to the repository.

cur---}$lHHd'A"}T-""'cOsRC{o""""""MEoncrcpst_-SntieooteUXTtatgusrlR-ecyinteeLPAnt"otaep/UPt_:nrlthaTI-i"y__op-Tn":_cani\Kyf橋code/epo本"odd"ryer市和der:e::m"歌e"epa,山":s"o$at県:s0sApi"""7iPpo,"6:3tIlnJ46o_i"P8"-rKc:"-東3iEa,0家3eYt{0一-s"i7丁0/o2目8a\n"69y/,番9yj2"as7-o号hn"t",m3\-5wkd
{}""isdl"u:g"4:66",ayya-htm3-5wkd"

Web UI confirmation: Repository detail page (with contact information)

The Contact area reflects the address and phone number.

Step 4: Register Donor (Authority Record)

Register Hanako Yamada, the donor of the historical photograph collection, as an authority record.

cur---}$lHHd'A"""""T-""'aehdpOsRC{unialMEottsta_-SnhitecUXTtotoseR-eryr_sLPAni_yo"/OPtzt"f:aSI-ey:_pT-Tdpe"iKy_e"x和/\epf_橋i歌ayeoi本s山c::rd市t県tm"在e橋o$a_:住n本rApoのc市sPpf1郷e"Il_3土"_in2史:Kca,研Eam究"Yte家1"i"。9o:25\n00/"2年j山5〜s田年"o花に,n子自""身,が\収集した橋本市の古写真コレクション（明治〜昭和期）を橋本市立図書館に寄贈した。",

entity_type_id: 132 means “Person.” Other options include 131=Corporate body and 133=Family.

Web UI confirmation: Authority record list

Step 5: Verify Donor Information

Web UI confirmation: Authority record detail page

The Identity area shows “Hanako Yamada” and “Person,” the Description area shows “1950-,” “Local history researcher residing in Hashimoto City…,” and “Wakayama Prefecture, Hashimoto City.”

Step 6: Create Accession Record

Create an accession record for the donated materials. Recording and managing the accession of materials is an essential procedure in archival work.

Key field meanings:

  • date: Accession date (required)
  • source_of_acquisition: Source of acquisition (required)
  • location_information: Storage location (required)
  • acquisition_type_id: 332 -> Gift
  • processing_status_id: 339 -> Incomplete
  • resource_type_id: 330 -> Private transfer
  • creators: [487] -> ID of Hanako Yamada created in Step 4

Web UI confirmation: Accession record list

Step 7: Update Processing Status

Since digitization work has begun, change the status to “In-Progress.”

Processing status changed to “In-Progress” and processing notes record the start of digitization work.

Web UI confirmation: Accession record detail page

Step 8: Check Taxonomies

In AtoM, values such as entity type, level of description, and acquisition type are managed as taxonomies. The entity_type_id and acquisition_type_id values used in previous steps are all taxonomy term IDs.

Commonly used taxonomy term ID reference table:

TaxonomyIDTerm
Actor Entity Types (32)131Corporate body
132Person
133Family
Levels of description (34)236Fonds
239Series
242Item
Description Detail (31)233Full
234Partial
Description Status (33)230Final
232Draft
Accession acquisition type (63)332Gift
333Purchase
Accession processing status (65)338Complete
339Incomplete
340In-Progress

Web UI confirmation: Taxonomy management screen

Step 9: Add Subject Classification

Add “Historical photographs” to the Subjects taxonomy (id=35) as a subject classification for the collection.

The i18n field enables multilingual support. The Japanese name is automatically saved with the culture setting at creation time.

Web UI confirmation: Subjects taxonomy

Step 10: Correct Classification Name

Change the term name to something more specific.

Step 11: Create Archival Description

Finally, create the archival description (Information Object) for the collection. This uses the existing arRestApiPlugin API.

  • level_of_description_id: 242 -> Item
  • publication_status_id: 160 -> Published
  • repository_id: 466 -> ID of Hashimoto City Library created in Step 1

Web UI confirmation: Archival description list

Step 12: Attach Digital Image

Upload the scanned photograph image with base64 encoding.

After uploading, AtoM automatically generates a reference copy and thumbnail.

Images can also be imported directly from URLs.

Web UI confirmation: Resource detail page

The Identity area displays the title “Hashimoto City Historical Photograph Collection Volume 1: Meiji Period Hashimoto” and identifier “HASH-PHOTO-001.” Digital object metadata shows the uploaded file’s metadata. Master file, Reference copy, and Thumbnail copy have been automatically generated.

Step 13: Check Final State

Check the data counts after completing all steps.

Compared to the initial state in Step 0, repositories, authority records, accession records, archival descriptions, and digital objects have increased.

Web UI confirmation: Top page

Additional Features

In addition to the basic scenario, here are other features available through arExtendedApiPlugin.

Function Description (ISDF) Management

Manage function descriptions compliant with ISDF (International Standard for Describing Functions). This is a mechanism for systematically recording the business functions of archive institutions.

  • type_id: 323 -> Function. 324=Subfunction is also selectable
  • Corresponds to ISDF fields (classification, dates, description, history, legislation)

Web UI confirmation: Function description list

Web UI confirmation: Function description detail

Place Taxonomy Management

Similar to Subjects, terms can be added to the Places taxonomy.

Web UI confirmation: Places taxonomy

Hierarchical Archival Descriptions

In AtoM, materials can be described in a hierarchical structure of Fonds > Series > Item. Use parent_id to establish parent-child relationships.

Web UI confirmation: Archival description detail (with hierarchy tree)

The tree on the left shows the Fonds > Series > Item hierarchy.

Repository Logo Image

Uploading a logo image to a repository displays it as a card on the list page.

Web UI confirmation: Repository list (card display with logo)

Web UI Confirmation URL List

A summary of Web UI screens to check at each step.

StepScreenURL
0Top pagehttp://localhost:63001
1Repository listhttp://localhost:63001/index.php/repository/browse
2-3Repository detailhttp://localhost:63001/index.php/ayya-htm3-5wkd
4Authority record listhttp://localhost:63001/index.php/actor/browse
5Authority record detailhttp://localhost:63001/index.php/wmdg-q5q2-4zy2
6Accession record listhttp://localhost:63001/index.php/accession/browse
7Accession record detailhttp://localhost:63001/index.php/2026-003
8Taxonomy listhttp://localhost:63001/index.php/taxonomy/browse
9-10Subjects taxonomyhttp://localhost:63001/index.php/subjects
11Archival description listhttp://localhost:63001/index.php/informationobject/browse
12Resource detail (with DO)http://localhost:63001/index.php/1
13Top pagehttp://localhost:63001
AddFunction description listhttp://localhost:63001/index.php/function/browse
AddPlaces taxonomyhttp://localhost:63001/index.php/places
AddRepository list (with logo)http://localhost:63001/index.php/repository/browse

Summary

In this article, we walked through AtoM’s REST API following a realistic business scenario of building a library digital archive.

By using the API:

  • Batch processing: Large volumes of material data can be registered at once via scripts
  • External integration: Data integration with other library systems and digitization vendor systems becomes easier
  • Automation: The workflow from accession to description to digitization to publication can be automated
  • Quality control: Data integrity checks can be incorporated by validating API responses

AtoM is proven software used by archive institutions worldwide. Leveraging REST API operations enables more efficient digital archive management.

Verification environment: AtoM 2.8.x (Docker), PHP 7.4, Percona 8.0, Elasticsearch 5.6