Archivematica API

From Archivematica
Revision as of 10:45, 11 December 2023 by Dcerna (talk | contribs) (Fix task property name)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Main Page > Development > Archivematica API

This page is no longer being maintained and may contain inaccurate information. Please see the Archivematica documentation for up-to-date information.

Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg ?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2) or as a header (eg Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2).

As GET parameters, format is:
?username=<username>&api_key=<api_key>

As a header, format is:
ApiKey <username>:<api_key>

NOTE: The 'ApiKey' prefix is a requirement of the Tastypie library in use. See the Tastypie docs for ApiKeyAuthentication.

Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body {'error': True, 'message': 'message describing error'}

Transfer

Start Transfer

  • URL: /api/transfer/start_transfer/
  • Verb: POST
  • Start a transfer.
  • Parameters: JSON body
    • name: Name of new transfer
    • type: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace
    • accession: Accession number of new transfer
    • paths[]: List of base64-encoded "<location_uuid>:<relative_path>" to be copied into the new transfer. Location UUIDs should be associated with this pipeline, and relative path should be relative to the location (TODO confirm relative vs absolute path). E.g. NWJiYWJjMTMtMTIyNy00MWE3LWIwY2QtZjJhYzM1MjkxZTdmOi92YWdyYW50L3NhbXBsZWRhdGEvQ1NWbWV0YWRhdGE= (decoded: 5bbabc13-1227-41a7-b0cd-f2ac35291e7f:/vagrant/sampledata/CSVmetadata)
    • row_ids[]: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]
  • Response: JSON
    • message: "Copy successful."
    • path: Path the transfer was copied to on start?

List Unapproved Transfers

  • URL: /api/transfer/unapproved
  • Verb: GET
  • Returns a list of transfers waiting for approval.
  • Response: JSON
    • message: "Fetched unapproved transfers successfully."
    • results: List of dicts with keys:
      • type: Transfer type. One of: standard, unzipped bag, zipped bag, dspace
      • directory: Directory the transfer is in currently
      • uuid: UUID of the transfer

Approve Transfer

  • URL: /api/transfer/approve
  • Verb: POST
  • Approve a transfer waiting to be started.
  • Parameters: JSON body
    • type: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.
    • directory: Name of the directory for the transfer to approve
  • Response: JSON
    • message: "Approval successful."
    • uuid: UUID of the approved transfer

Status

  • URL: /api/transfer/status/<transfer UUID>/
  • Verb: GET
  • Returns the status of the transfer.
  • Response: JSON
    • status: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING
    • name: Name of the transfer, e.g. "imgs"
    • sip_uuid: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'
    • microservice: Name of the current microservice
    • directory: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"
    • path: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"
    • message: "Fetched status for <transfer UUID> successfully."
    • type: "transfer"
    • uuid: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"

Note: for consumers of this endpoint, it is possible for Archivematica to return a status of COMPLETE without a sip_uuid. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a status of COMPLETE and the existence of sip_uuid that does not also equal BACKLOG to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.

Hide

  • URL: /api/transfer/<transfer UUID>/delete/
  • Verb: DELETE
  • Hide a transfer
  • Response: JSON
    • removed: True

Completed

  • URL: /api/transfer/completed/
  • Verb: GET
  • Return list of Transfers that are completed
  • Response: JSON
    • message: "Fetched completed transfers successfully."
    • results: List of UUIDs of completed Transfers
  • Added in Archivematica 1.6

Start Reingest

  • URL: /api/transfer/reingest
  • Verb: POST
  • Start a full reingest.
  • Parameters: JSON body
    • name: Name of the AIP. The AIP should also be found at %sharedDirectory%/tmp/<name>
    • uuid: UUID of the AIP to reingest
  • Response: JSON
    • message: "Approval successful."
    • reingest_uuid: UUID of the reingested transfer

Ingest

Status

  • URL: /ingest/status/<unit UUID>/
  • Verb: GET
  • Returns the status of the SIP
  • Response: JSON
    • status: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING
    • name: Name of the SIP, e.g. "imgs"
    • microservice: Name of the current microservice
    • directory: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"
    • path: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"
    • message: "Fetched status for <SIP UUID> successfully."
    • type: "SIP"
    • uuid: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"

Hide

  • URL: /api/ingest/<SIP UUID>/delete/
  • Verb: DELETE
  • Hide a SIP
  • Response: JSON
    • removed: True

List SIPS Waiting for User Input

  • URL: /api/ingest/waiting
  • Verb: GET
  • Returns a list of SIPs waiting for user input.
  • Response: JSON
    • message: "Fetched units successfully."
    • results: List of dicts with keys:
      • sip_directory: Directory the SIP is in currently
      • sip_uuid: UUID of the SIP
      • sip_name: Name of the SIP
      • microservice: Name of the current microservice
Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate /api/transfer/waiting should be added for transfers.

Completed

  • URL: /api/ingest/completed/
  • Verb: GET
  • Return list of SIPs that are completed
  • Response: JSON
    • message: "Fetched completed ingests successfully."
    • results: List of UUIDs of completed SIPs
  • Added in Archivematica 1.6

Reingest

  • URL: /api/ingest/reingest
  • Verb: POST
  • Start a partial or metadata-only reingest.
  • Parameters: JSON body
    • name: Name of the AIP. The AIP should also be found at %sharedDirectory%/tmp/<name>
    • uuid: UUID of the AIP to reingest
  • Response: JSON
    • message: "Approval successful."
    • reingest_uuid: UUID of the reingested SIP

Copy Metadata

  • URL: /api/ingest/copy_metadata_files/
  • Verb: POST
  • Add metadata files to a SIP.
  • Parameters: JSON body
    • sip_uuid: UUID of the SIP to put files in
    • source_paths[]: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'
  • Response: JSON
    • error: False
    • message: "Files added successfully."

Administration

Levels of Description

  • URL: /api/administration/dips/atom/levels/
  • Verb: GET?
  • Return a JSON-encoded set of the configured levels of description.
  • Response: JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.

Fetch Levels of Description

  • URL: /api/administration/dips/atom/fetch_levels/
  • Verb: GET?
  • Fetch all levels of description from an AtoM database, replacing any previously existing.
  • Response: JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.

Unit

Note: Currently, you can only query strings in English.

List jobs

  • URL: /api/v2beta/jobs/<unit UUID>/
  • Verb: GET
  • Return a list of jobs for the passed unit (transfer or ingest).
  • Parameters:
  • Optional filters:
      • microservice: Name of the microservice the jobs belong to
      • link_uuid: UUID of the job chain link
      • name: Name of the job
  • Response: JSON body
    • List of dicts with keys:
      • uuid: UUID of the job
      • name: Name of the job
      • status: One of USER_INPUT, PROCESSING, COMPLETE, FAILED or UNKNOWN
      • microservice: Microservice the job belongs to
      • link_uuid: UUID of the job chain link
      • tasks: List of dicts with information about the microservice's tasks:
      • uuid: UUID of the task
      • exit_code: Exit code of the task

Task

  • URL: /api/v2beta/task/<task UUID>/
  • Verb: GET
  • Return information about a task.
  • Response: JSON body
    • uuid: UUID of the task
    • exit_code: Exit code of the task
    • file_uuid: UUID of the file used for the task
    • file_name: File used for the task,
    • time_created: String (YYYY-MM-DD HH:MM:SS) representing when the task was created
    • time_started: String (YYYY-MM-DD HH:MM:SS) representing when the task started
    • time_ended: String (YYYY-MM-DD HH:MM:SS) representing when the task finished
    • duration: Task duration in seconds (integer). If the duration is less than a second, this will be a < 1 string

Other

Path Metadata

  • URL: /api/filesystem/metadata/
  • Verb: GET, POST
  • Fetch (GET) or update (POST) metadata for a path (currently only level of description).
  • Parameters: Query string parameters (GET) or JSON body (POST)
    • path: Arranged path to get metadata on
  • GET response: JSON
    • level_of_description: Level of description
  • POST response: JSON
    • success: True

Processing Configuration

  • URL: /api/processing-configuration/<name>
  • Verb: GET?
  • Return processing configuration with <name>
  • Response: The processing config file as a stream.
  • Content type: text/xml

Beta endpoints

API endpoints which are still in-flux and that could potentially change.

Package

Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.

  • URL: /api/v2beta/package
  • Verb: POST
  • Start a new transfer type.
  • Parameters: JSON body
    • Mandatory
      • name: Transfer name
      • path: Path relative, or absolute to a storage service transfer source
    • Optional
      • type: Transfer type, e.g. standard, dataverse, zipped bag, default: standard
      • processing_config: Processing configuration, e.g. default, automated, default: default
      • accession: Accession ID
      • access_system_id: Access system ID (see docs)
      • metadata_set_id: Used to link to metadata sets added via the user interface. It's safe to ignore this for now since metadata can't be associated to transfer via the API at the moment.
      • auto_approve: Boolean true or false to set the transfer to auto-approve, default: true
  • Response: JSON
    • id: Transfer UUID (Note: as the package endpoint allows the caller to interact with Archivematica asynchronously it doesn't guarantee a transfer has started. The caller must use the UUID in the response to verify it has begun or any errors that were encountered initiating one.)

Examples:
Only a subset of these options might be needed for most use-cases. A fundamental difference between the package endpoint and others from which a transfer can be initiated is that a storage service transfer location UUID isnt always required. In some cases that might still be ideal.

Starting a transfer using an absolute path: 

   curl -v POST \
     -H "Authorization: ApiKey test:test" \
     -H "Content-Type: application/json" \
     -d "{\
         \"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransferCSV' | base64 -w 0)\", \
         \"name\": \"demo_transfer_absolute\", \
         \"processing_config\": \"automated\", \
         \"type\": \"standard\" \
         }" \
    "http://<archivematica-uri>/api/v2beta/package"

Starting a transfer using an relative path with a transfer source UUID: 

   curl -v POST \
     -H "Authorization: ApiKey test:test" \
     -H "Content-Type: application/json" \
     -d "{\
         \"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransferCSV' | base64 -w 0)\", \
         \"name\": \"demo_transfer_relative\", \
         \"processing_config\": \"automated\", \
         \"type\": \"standard\" \
         }" \
    "http://<archivematica-uri>/api/v2beta/package"

Validate

Available in Archivematica 1.10+. This endpoint can be used to validate CSVs against embedded sets of rules. Currently works with Avalon Media System Manifest files.

In the future, this endpoint can be extended to support validation for metadata.csv or rights.csv, or other institutionally-based rules.


  • URL: /api/v2beta/validate/avalon
  • Content-Type: text/csv; charset=utf-8
  • Parameters: <document>

Usage example: (assuming that avalon.csv exists) 

curl http://127.0.0.1:62080/api/v2beta/validate/avalon \
  --data-binary "@avalon.csv" \
  --header "Authorization: ApiKey test:test" \
  --header "Content-Type: text/csv; charset=utf-8"


Response examples:

200 OK 

{
  "valid": true
}


400 Bad Request (expect reason to include different validation errors) 

{
  "valid": false,
  "reason": "Administrative data must include reference name and author."
}

404 Not Found 


{
  "error": true,
  "message": "Unknown validator. Accepted values: avalon"
}
Retrieved from "https://wiki.archivematica.org/index.php?title=Archivematica_API&oldid=13705"