Difference between revisions of "Archivematica API"

From Archivematica
Jump to navigation Jump to search
Line 211: Line 211:
 
* '''Response''': JSON
 
* '''Response''': JSON
 
** <code>id</code>: Transfer UUID
 
** <code>id</code>: Transfer UUID
−
 
+
'''Examples:'''
 +
<br/>
 +
Only a subset of these options might be needed for most use-cases. A fundamental difference between the <code>package</code> 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.
 +
<br/><br/>
 +
''Starting a transfer using an absolute path:''
 +
<br/>
 +
<pre>
 +
  curl -v POST \
 +
    -H "Authorization: ApiKey test:test" \
 +
    -H "Content-Type: application/json" \
 +
    -d "{\
 +
        \"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \
 +
        \"name\": \"demo_transfer_absolute\", \
 +
        \"processing_config\": \"automated\", \
 +
        \"type\": \"standard\" \
 +
        }" \
 +
    "http://<archivematica-uri>/api/v2beta/package"
 +
</pre>
 +
''Starting a transfer using an relative path with a transfer source UUID:''
 +
<br/>
 +
<pre>
 +
  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/DemoTransfer' | base64 -w 0)\", \
 +
        \"name\": \"demo_transfer_relative\", \
 +
        \"processing_config\": \"automated\", \
 +
        \"type\": \"standard\" \
 +
        }" \
 +
    "http://<archivematica-uri>/api/v2beta/package"
 +
</pre>
 
[[Category:Development documentation]]
 
[[Category:Development documentation]]

Revision as of 15:08, 26 February 2019

Main Page > Development > Archivematica API

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)

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: /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"

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?
  • Returns 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'.

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
    • name: Transfer name
    • type: Transfer type, e.g. standard, dataverse, zipped bag, default: standard
    • accession: Accession ID
    • accession_system_id: TBC
    • path: Path relative, or absolute to a storage service transfer source
    • metadata_set_id: TBC
    • auto_apptove: Boolean True or False to set the transfer to auto-approve, default: True
    • wait_until_complete: TBC
  • Response: JSON
    • id: Transfer UUID

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/DemoTransfer' | 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/DemoTransfer' | base64 -w 0)\", \
         \"name\": \"demo_transfer_relative\", \
         \"processing_config\": \"automated\", \
         \"type\": \"standard\" \
         }" \
    "http://<archivematica-uri>/api/v2beta/package"
Retrieved from "https://wiki.archivematica.org/index.php?title=Archivematica_API&oldid=12895"