https://wiki.archivematica.org/api.php?action=feedcontributions&feedformat=atom&user=McurranArchivematica - User contributions [en]2026-05-02T17:41:47ZUser contributionsMediaWiki 1.35.4https://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13131Archivematica API2019-07-12T16:41:54Z<p>Mcurran: Added note regarding limitation of string queries.</p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br \><br \><br />
''As GET parameters, format is:''<br \><br />
<code>?username=<''username''>&api_key=<''api_key''></code><br \><br />
<br />
''As a header, format is:''<br \><br />
<code>ApiKey <username>:<api_key></code><br \><br />
<br />
'''NOTE:''' The 'ApiKey' prefix is a requirement of the Tastypie library in use. See the Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br \><br \><br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/api/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Return a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Unit ==<br />
<br />
''Note: Currently, you can only query strings in English.''<br />
<br />
=== List jobs ===<br />
* '''URL''': <code>/v2beta/jobs/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Return a list of jobs for the passed unit (transfer or ingest).<br />
* '''Parameters''':<br />
* '''Optional filters''':<br />
*** <code>microservice</code>: Name of the microservice the jobs belong to<br />
*** <code>link_uuid</code>: UUID of the job chain link<br />
*** <code>name</code>: Name of the job<br />
* '''Response''': JSON body<br />
** '''List of dicts with keys''':<br />
*** <code>uuid</code>: UUID of the job<br />
*** <code>name</code>: Name of the job<br />
*** <code>status</code>: One of USER_INPUT, PROCESSING, COMPLETE, FAILED or UNKNOWN<br />
*** <code>microservice</code>: Microservice the job belongs to<br />
*** <code>link_uuid</code>: UUID of the job chain link<br />
*** <code>tasks</code>: List of dicts with information about the microservice's tasks:<br />
*** <code>uuid</code>: UUID of the task<br />
*** <code>exit_code</code>: Exit code of the task<br />
<br />
=== Task ===<br />
* '''URL''': <code>/v2beta/task/<task UUID>/</code><br />
* '''Verb''': GET<br />
* Return information about a task.<br />
* '''Response''': JSON body<br />
** <code>uuid</code>: UUID of the task<br />
** <code>exit_code</code>: Exit code of the task<br />
** <code>file_uuid</code>: UUID of the file used for the task<br />
** <code>file_name</code>: File used for the task,<br />
** <code<time_created</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task was created<br />
** <code>time_started</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task started<br />
** <code>time_ended</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task finished<br />
** <code>duration</code>: Task duration in seconds (integer). If the duration is less than a second, this will be a < 1 string<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13127Archivematica API2019-07-12T00:47:48Z<p>Mcurran: Removed extra character</p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br \><br \><br />
''As GET parameters, format is:''<br \><br />
<code>?username=<''username''>&api_key=<''api_key''></code><br \><br />
<br />
''As a header, format is:''<br \><br />
<code>ApiKey <username>:<api_key></code><br \><br />
<br />
'''NOTE:''' The 'ApiKey' prefix is a requirement of the Tastypie library in use. See the Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br \><br \><br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/api/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Return a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Unit ==<br />
<br />
=== List jobs ===<br />
* '''URL''': <code>/v2beta/jobs/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Return a list of jobs for the passed unit (transfer or ingest).<br />
* '''Parameters''':<br />
* '''Optional filters''':<br />
*** <code>microservice</code>: Name of the microservice the jobs belong to<br />
*** <code>link_uuid</code>: UUID of the job chain link<br />
*** <code>name</code>: Name of the job<br />
* '''Response''': JSON body<br />
** '''List of dicts with keys''':<br />
*** <code>uuid</code>: UUID of the job<br />
*** <code>name</code>: Name of the job<br />
*** <code>status</code>: One of USER_INPUT, PROCESSING, COMPLETE, FAILED or UNKNOWN<br />
*** <code>microservice</code>: Microservice the job belongs to<br />
*** <code>link_uuid</code>: UUID of the job chain link<br />
*** <code>tasks</code>: List of dicts with information about the microservice's tasks:<br />
*** <code>uuid</code>: UUID of the task<br />
*** <code>exit_code</code>: Exit code of the task<br />
<br />
=== Task ===<br />
* '''URL''': <code>/v2beta/task/<task UUID>/</code><br />
* '''Verb''': GET<br />
* Return information about a task.<br />
* '''Response''': JSON body<br />
** <code>uuid</code>: UUID of the task<br />
** <code>exit_code</code>: Exit code of the task<br />
** <code>file_uuid</code>: UUID of the file used for the task<br />
** <code>file_name</code>: File used for the task,<br />
** <code<time_created</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task was created<br />
** <code>time_started</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task started<br />
** <code>time_ended</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task finished<br />
** <code>duration</code>: Task duration in seconds (integer). If the duration is less than a second, this will be a < 1 string<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13126Archivematica API2019-07-12T00:45:46Z<p>Mcurran: Added microservices and task API endpoints per @replaceafill. #722</p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br \><br \><br />
''As GET parameters, format is:''<br \><br />
<code>?username=<''username''>&api_key=<''api_key''></code><br \><br />
<br />
''As a header, format is:''<br \><br />
<code>ApiKey <username>:<api_key></code><br \><br />
<br />
'''NOTE:''' The 'ApiKey' prefix is a requirement of the Tastypie library in use. See the Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br \><br \><br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/api/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Return a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Unit ==<br />
<br />
=== List jobs ===<br />
* '''URL''': <code>/v2beta/jobs/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Return a list of jobs for the passed unit (transfer or ingest).<br />
* '''Parameters''':<br />
* *'''Optional filters''':<br />
*** <code>microservice</code>: Name of the microservice the jobs belong to<br />
*** <code>link_uuid</code>: UUID of the job chain link<br />
*** <code>name</code>: Name of the job<br />
* '''Response''': JSON body<br />
** '''List of dicts with keys''':<br />
*** <code>uuid</code>: UUID of the job<br />
*** <code>name</code>: Name of the job<br />
*** <code>status</code>: One of USER_INPUT, PROCESSING, COMPLETE, FAILED or UNKNOWN<br />
*** <code>microservice</code>: Microservice the job belongs to<br />
*** <code>link_uuid</code>: UUID of the job chain link<br />
*** <code>tasks</code>: List of dicts with information about the microservice's tasks:<br />
*** <code>uuid</code>: UUID of the task<br />
*** <code>exit_code</code>: Exit code of the task<br />
<br />
=== Task ===<br />
* '''URL''': <code>/v2beta/task/<task UUID>/</code><br />
* '''Verb''': GET<br />
* Return information about a task.<br />
* '''Response''': JSON body<br />
** <code>uuid</code>: UUID of the task<br />
** <code>exit_code</code>: Exit code of the task<br />
** <code>file_uuid</code>: UUID of the file used for the task<br />
** <code>file_name</code>: File used for the task,<br />
** <code<time_created</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task was created<br />
** <code>time_started</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task started<br />
** <code>time_ended</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task finished<br />
** <code>duration</code>: Task duration in seconds (integer). If the duration is less than a second, this will be a < 1 string<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13125Archivematica API2019-07-12T00:37:30Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br \><br \><br />
''As GET parameters, format is:''<br \><br />
<code>?username=<''username''>&api_key=<''api_key''></code><br \><br />
<br />
''As a header, format is:''<br \><br />
<code>ApiKey <username>:<api_key></code><br \><br />
<br />
'''NOTE:''' The 'ApiKey' prefix is a requirement of the Tastypie library in use. See the Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br \><br \><br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/api/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Return a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Unit ==<br />
<br />
=== List jobs ===<br />
* '''URL''': /v2beta/jobs/<unit UUID>/<br />
* '''Verb''': GET<br />
* Return a list of jobs for the passed unit (transfer or ingest).<br />
* '''Parameters''':<br />
* *'''Optional filters''':<br />
*** <code>microservice</code>: Name of the microservice the jobs belong to<br />
*** <code>link_uuid</code>: UUID of the job chain link<br />
*** <code>name</code>: Name of the job<br />
* '''Response''': JSON body<br />
** '''List of dicts with keys''':<br />
*** <code>uuid</code>: UUID of the job<br />
*** <code>name</code>: Name of the job<br />
*** <code>status</code>: One of USER_INPUT, PROCESSING, COMPLETE, FAILED or UNKNOWN<br />
*** <code>microservice</code>: Microservice the job belongs to<br />
*** <code>link_uuid</code>: UUID of the job chain link<br />
*** <code>tasks</code>: List of dicts with information about the microservice's tasks:<br />
*** <code>uuid</code>: UUID of the task<br />
*** <code>exit_code</code>: Exit code of the task<br />
<br />
=== Task ===<br />
* '''URL''': /v2beta/task/<task UUID>/<br />
* '''Verb''': GET<br />
* Return information about a task.<br />
* '''Response''': JSON body<br />
** <code>uuid</code>: UUID of the task<br />
** <code>exit_code</code>: Exit code of the task<br />
** <code>file_uuid</code>: UUID of the file used for the task<br />
** <code>file_name</code>: File used for the task,<br />
** <code<time_created</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task was created<br />
** <code>time_started</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task started<br />
** <code>time_ended</code>: String (YYYY-MM-DD HH:MM:SS) representing when the task finished<br />
** <code>duration</code>: Task duration in seconds (integer). If the duration is less than a second, this will be a < 1 string<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13117Archivematica API2019-07-05T00:21:07Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br \><br \><br />
''As GET parameters, format is:''<br \><br />
<code>?username=<''username''>&api_key=<''api_key''></code><br \><br />
<br />
''As a header, format is:''<br \><br />
<code>ApiKey <username>:<api_key></code><br \><br />
<br />
'''NOTE:''' The 'ApiKey' prefix is a requirement of the Tastypie library in use. See the Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br \><br \><br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13116Archivematica API2019-07-05T00:20:25Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br \><br \><br />
''As GET parameters, format is:''<br \><br />
<code>?username=<''username''>&api_key=<''your api key''></code><br \><br />
<br />
''As a header, format is:''<br \><br />
<code>ApiKey <username>:<api_key></code><br \><br />
<br />
'''NOTE:''' The 'ApiKey' prefix is a requirement of the Tastypie library in use. See the Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br \><br \><br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13115Archivematica API2019-07-05T00:18:45Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br \><br \><br />
''As GET parameters, format is:''<br \><br />
<code>?username=demo&api_key=<your api key></code><br \><br />
<br />
''As a header, format is:''<br \><br />
<code>ApiKey <username>:<api_key></code><br \><br />
<br />
'''NOTE:''' The 'ApiKey' prefix is a requirement of the Tastypie library in use. See the Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br \><br \><br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13114Archivematica API2019-07-04T23:35:52Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key></code><br />
See Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br \><br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13113Archivematica API2019-07-04T23:33:51Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key></code>&nbsp;&nbsp;<br />
<br />
See Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13112Archivematica API2019-07-04T23:33:17Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
''NOTE:<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key></code>&nbsp;<br />
See Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].''<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13111Archivematica API2019-07-04T23:32:17Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key></code>&nbsp;<br />
See Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication ApiKeyAuthentication].<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13110Archivematica API2019-07-04T23:31:47Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key></code>&nbsp;<br />
See Tastypie docs for [https://django-tastypie.readthedocs.io/en/latest/authentication.html#apikeyauthentication APIKeyAuthentication].<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13109Archivematica API2019-07-04T23:28:54Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key></code>&nbsp;<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13108Archivematica API2019-07-04T23:28:29Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key></code><br \><br \><br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13107Archivematica API2019-07-04T23:27:58Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key></code><br />
<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13106Archivematica API2019-07-04T23:27:22Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key><code><br />
<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13105Archivematica API2019-07-04T23:26:42Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key><code> <br \><br />
Example: <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code><br />
<br />
<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13104Archivematica API2019-07-04T23:25:53Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is as follows: <br \><br />
<code>ApiKey <username>:<api_key><code> <br \><br />
For example: <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code><br />
<br />
<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13103Archivematica API2019-07-04T23:24:02Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br \><br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is `ApiKey <username>:<api_key>`; the above example is <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code><br />
<br />
<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13102Archivematica API2019-07-04T23:23:11Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:''' &nbsp;&nbsp;<br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is `ApiKey <username>:<api_key>`; the above example is <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code><br />
<br />
<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13101Archivematica API2019-07-04T23:22:44Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:''' &nbsp;<br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is `ApiKey <username>:<api_key>`; the above example is <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code><br />
<br />
<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_API&diff=13100Archivematica API2019-07-04T23:22:12Z<p>Mcurran: </p>
<hr />
<div>[[Main Page]] > [[Development]] > Archivematica API<br />
<br />
Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg <code>?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>) or as a header (eg <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code>).<br />
<br />
'''NOTE:'''<br />
When submitting as a header, be sure to include the 'ApiKey' prefix, as this is the required formatting for the Tastypie library in use.<br />
In other words, the header format is `ApiKey <username>:<api_key>`; the above example is <code>Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2</code><br />
<br />
<br />
<br />
Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body <code>{'error': True, 'message': 'message describing error'}</code><br />
<br />
== Transfer ==<br />
<br />
=== Start Transfer ===<br />
* '''URL''': <code>/api/transfer/start_transfer/</code><br />
* '''Verb''': POST<br />
* Start a transfer.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of new transfer<br />
** <code>type</code>: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace<br />
** <code>accession</code>: Accession number of new transfer<br />
** <code>paths[]</code>: 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)<br />
** <code>row_ids[]</code>: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]<br />
* '''Response''': JSON<br />
** <code>message</code>: "Copy successful."<br />
** <code>path</code>: Path the transfer was copied to on start?<br />
<br />
=== List Unapproved Transfers ===<br />
* '''URL''': <code>/api/transfer/unapproved</code><br />
* '''Verb''': GET<br />
* Returns a list of transfers waiting for approval.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched unapproved transfers successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>type</code>: Transfer type. One of: standard, unzipped bag, zipped bag, dspace<br />
*** <code>directory</code>: Directory the transfer is in currently<br />
*** <code>uuid</code>: UUID of the transfer<br />
<br />
=== Approve Transfer ===<br />
* '''URL''': <code>/api/transfer/approve</code><br />
* '''Verb''': POST<br />
* Approve a transfer waiting to be started.<br />
* '''Parameters''': JSON body<br />
** <code>type</code>: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.<br />
** <code>directory</code>: Name of the directory for the transfer to approve<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>uuid</code>: UUID of the approved transfer<br />
<br />
=== Status ===<br />
* '''URL''': <code>/transfer/status/<transfer UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the transfer.<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the transfer, e.g. "imgs"<br />
** <code>sip_uuid</code>: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <transfer UUID> successfully."<br />
** <code>type</code>: "transfer"<br />
** <code>uuid</code>: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
'''Note:''' for consumers of this endpoint, it is possible for Archivematica to return a <code>status</code> of <code>COMPLETE</code> without a <code>sip_uuid</code>. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a <code>status</code> of <code>COMPLETE</code> and the existence of <code>sip_uuid</code> that does not also equal <code>BACKLOG</code> to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/transfer/<transfer UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a transfer<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/transfer/completed/</code><br />
* '''Verb''': GET<br />
* Return list of Transfers that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed transfers successfully."<br />
** <code>results</code>: List of UUIDs of completed Transfers<br />
* Added in Archivematica 1.6<br />
<br />
=== Start Reingest ===<br />
* '''URL''': <code>/api/transfer/reingest</code><br />
* '''Verb''': POST<br />
* Start a full reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested transfer<br />
<br />
== Ingest ==<br />
<br />
=== Status ===<br />
* '''URL''': <code>/ingest/status/<unit UUID>/</code><br />
* '''Verb''': GET<br />
* Returns the status of the SIP<br />
* '''Response''': JSON<br />
** <code>status</code>: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING<br />
** <code>name</code>: Name of the SIP, e.g. "imgs"<br />
** <code>microservice</code>: Name of the current microservice<br />
** <code>directory</code>: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
** <code>path</code>: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"<br />
** <code>message</code>: "Fetched status for <SIP UUID> successfully."<br />
** <code>type</code>: "SIP"<br />
** <code>uuid</code>: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"<br />
<br />
=== Hide ===<br />
* '''URL''': <code>/api/ingest/<SIP UUID>/delete/</code><br />
* '''Verb''': DELETE<br />
* Hide a SIP<br />
* '''Response''': JSON<br />
** <code>removed</code>: True<br />
<br />
=== List SIPS Waiting for User Input ===<br />
* '''URL''': <code>/api/ingest/waiting</code><br />
* '''Verb''': GET<br />
* Returns a list of SIPs waiting for user input.<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched units successfully."<br />
** <code>results</code>: List of dicts with keys:<br />
*** <code>sip_directory</code>: Directory the SIP is in currently<br />
*** <code>sip_uuid</code>: UUID of the SIP<br />
*** <code>sip_name</code>: Name of the SIP<br />
*** <code>microservice</code>: Name of the current microservice<br />
<br />
{| class="wikitable" style="background-color:#ffeecc;" cellpadding="10";<br />
| Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate <code>/api/transfer/waiting</code> should be added for transfers.<br />
|}<br />
<br />
=== Completed ===<br />
* '''URL''': <code>/api/ingest/completed/</code><br />
* '''Verb''': GET<br />
* Return list of SIPs that are completed<br />
* '''Response''': JSON<br />
** <code>message</code>: "Fetched completed ingests successfully."<br />
** <code>results</code>: List of UUIDs of completed SIPs<br />
* Added in Archivematica 1.6<br />
<br />
=== Reingest ===<br />
* '''URL''': <code>/api/ingest/reingest</code><br />
* '''Verb''': POST<br />
* Start a partial or metadata-only reingest.<br />
* '''Parameters''': JSON body<br />
** <code>name</code>: Name of the AIP. The AIP should also be found at <code>%sharedDirectory%/tmp/<name></code><br />
** <code>uuid</code>: UUID of the AIP to reingest<br />
* '''Response''': JSON<br />
** <code>message</code>: "Approval successful."<br />
** <code>reingest_uuid</code>: UUID of the reingested SIP<br />
<br />
=== Copy Metadata ===<br />
* '''URL''': <code>/api/ingest/copy_metadata_files/</code><br />
* '''Verb''': POST<br />
* Add metadata files to a SIP.<br />
* '''Parameters''': JSON body<br />
** <code>sip_uuid</code>: UUID of the SIP to put files in<br />
** <code>source_paths[]</code>: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'<br />
* '''Response''': JSON<br />
** <code>error</code>: False<br />
** <code>message</code>: "Files added successfully."<br />
<br />
== Administration ==<br />
<br />
=== Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/levels/</code><br />
* '''Verb''': GET?<br />
* Returns a JSON-encoded set of the configured levels of description.<br />
* ''Response'': JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
=== Fetch Levels of Description ===<br />
* '''URL''': <code>/api/administration/dips/atom/fetch_levels/</code><br />
* '''Verb''': GET?<br />
* Fetch all levels of description from an AtoM database, replacing any previously existing.<br />
* '''Response''': JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.<br />
<br />
== Other ==<br />
<br />
=== Path Metadata ===<br />
* '''URL''': <code>/api/filesystem/metadata/</code><br />
* '''Verb''': GET, POST<br />
* Fetch (GET) or update (POST) metadata for a path (currently only level of description).<br />
* '''Parameters''': Query string parameters (GET) or JSON body (POST)<br />
** <code>path</code>: Arranged path to get metadata on<br />
* '''GET response''': JSON<br />
** <code>level_of_description</code>: Level of description<br />
* '''POST response''': JSON<br />
** <code>success</code>: True<br />
<br />
=== Processing Configuration ===<br />
* '''URL''': <code>/api/processing-configuration/<name></code><br />
* '''Verb''': GET?<br />
* Return processing configuration with <name><br />
* '''Response''': The processing config file as a stream.<br />
* '''Content type''': text/xml<br />
<br />
== Beta endpoints ==<br />
<br />
API endpoints which are still in-flux and that could potentially change. <br />
<br />
=== Package ===<br />
<br />
Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.<br />
<br />
* '''URL''': <code>/api/v2beta/package</code><br />
* '''Verb''': POST<br />
* Start a new transfer type.<br />
* '''Parameters''': JSON body<br />
** Mandatory<br />
*** <code>name</code>: Transfer name<br />
*** <code>path</code>: Path relative, or absolute to a storage service transfer source<br />
**Optional<br />
*** <code>type</code>: Transfer type, e.g. standard, dataverse, zipped bag, default: <code>standard</code><br />
*** <code>processing_config</code>: [https://www.archivematica.org/en/docs/latest/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration], e.g. default, automated, default: <code>default</code><br />
*** <code>accession</code>: Accession ID<br />
*** <code>access_system_id</code>: Access system ID (see [https://www.archivematica.org/en/docs/latest/user-manual/access/access docs])<br />
*** <code>metadata_set_id</code>: 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.<br />
*** <code>auto_approve</code>: Boolean <code>True</code> or <code>False</code> to set the transfer to auto-approve, default: <code>True</code><br />
* '''Response''': JSON<br />
** <code>id</code>: 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.)<br />
'''Examples:'''<br />
<br/><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/><br/><br />
''Starting a transfer using an absolute path:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_absolute\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
''Starting a transfer using an relative path with a transfer source UUID:''<br />
<br/><br />
<pre><br />
curl -v POST \<br />
-H "Authorization: ApiKey test:test" \<br />
-H "Content-Type: application/json" \<br />
-d "{\<br />
\"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \<br />
\"name\": \"demo_transfer_relative\", \<br />
\"processing_config\": \"automated\", \<br />
\"type\": \"standard\" \<br />
}" \<br />
"http://<archivematica-uri>/api/v2beta/package"<br />
</pre><br />
<br />
<br />
=== Validate ===<br />
<br />
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.<br />
<br />
In the future, this endpoint can be extended to support validation for <code>metadata.csv</code> or <code>rights.csv</code>, or other institutionally-based rules.<br />
<br />
<br />
* '''URL''': <code>/api/v2beta/validate/avalon</code><br />
* '''Content-Type''': text/csv; charset=utf-8<br />
* '''Parameters''': <code><document></code><br />
<br />
Usage example: (assuming that <code>avalon.csv</code> exists)<br />
<br />
<pre><br />
curl http://127.0.0.1:62080/api/v2beta/validate/avalon \<br />
--data-binary "@avalon.csv" \<br />
--header "Authorization: ApiKey test:test" \<br />
--header "Content-Type: text/csv; charset=utf-8"<br />
</pre><br />
<br />
<br />
Response examples:<br />
<br />
200 OK<br />
<br />
<pre><br />
{<br />
"valid": true<br />
}<br />
</pre><br />
<br />
<br />
400 Bad Request (expect reason to include different validation errors)<br />
<br />
<pre><br />
{<br />
"valid": false,<br />
"reason": "Administrative data must include reference name and author."<br />
}<br />
</pre><br />
<br />
404 Not Found<br />
<br />
<br />
<pre><br />
{<br />
"error": true,<br />
"message": "Unknown validator. Accepted values: avalon"<br />
}<br />
</pre><br />
<br />
<br />
<br />
[[Category:Development documentation]]</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_1.8_and_Storage_Service_0.13_release_notes&diff=12736Archivematica 1.8 and Storage Service 0.13 release notes2018-10-25T19:56:08Z<p>Mcurran: /* Fixed */</p>
<hr />
<div>[[Main_Page|Home]] > [[Release_Notes|Release Notes]] > Major release notes template<br />
<br />
'''Work in progress'''<br />
<br />
==Supported environments==<br />
<br />
Link to installation instructions.<br />
<br />
Specify supported environments.<br />
<br />
Make special note of any changes to supported environment.<br />
<br />
==Added==<br />
<br />
===Dataverse integration===<br />
<br />
Archivematica can now be configured to use a [https://dataverse.org/ Dataverse] research data repository as a transfer source location. Dataverse transfer source locations can be configured to display all available datasets or a subset of them. Datasets are retrieved directly using the Dataverse API and processed using a new “Dataverse” transfer type. New dataverse specific processing includes:<br />
<br />
* fixity checking using checksums generated by dataverse<br />
* retrieval of derivative and metadata files associated with tabular data files<br />
* creation of a Dataverse METS file describing the dataset as retrieved from Dataverse<br />
* Dataverse metadata included in the AIP METS<br />
<br />
Some advanced or more complex use cases are not fully supported, such as handling of datasets with restricted files, versioning of datasets and reingest of datasets. For a full list of known issues and enhancement ideas, refer to the [https://github.com/archivematica/Issues/labels/OCUL%3A%20AM-Dataverse Archivematica issues repository using Dataverse label] and the [https://wiki.archivematica.org/Dataverse Archivematica Wiki]. <br />
<br />
This work was sponsored by [https://scholarsportal.info/ Scholars Portal], a service of the Ontario Council of University Libraries (OCUL). Thank you!<br />
<br />
* Issue: See [https://waffle.io/artefactual/archivematica?label=OCUL:%20AM-Dataverse waffle board] for all issues with the Dataverse label. <br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/transfer/dataverse/ Dataverse Integration]<br />
<br />
===Processing configuration reset and download buttons===<br />
<br />
A new installation of Archivematica comes with a pre-set processing configuration called "default", and a second one (used only in Jisc workflows) called "automated". In testing, users are encouraged to change the configurations to suit their workflows, but may need to reset the configuration to the installation pre-sets. A reset button has been added so that users can easily change the default and automated processing configurations back to their installation pre-sets.<br />
<br />
The second part of this feature is the addition of a download button for the processing configuration files. If you create a custom processing configuration, you can download the resulting processingMCP.xml file using the button and then include it at the top level of your transfer. Archivematica will then use this to automate your transfer selections, rather than the default configuration.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1138 #1138]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration documentation]<br />
<br />
===Public URL===<br />
<br />
Archivematica now has a concept of a public URL in the general configuration. Archivematica usually registers itself with the Storage Service, but if you have deployed Archivematica in an environment where the URL or IP address changes frequently (i.e. in some Docker environments) this can cause issues. In these types of environments, users can now declare a stable public URL that Archivematica can use to register with the Storage Service.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1140 1140]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/admin-manual/installation-setup/customization/dashboard-config/#admin-dashboard-general General configuration]<br />
<br />
==Changed==<br />
<br />
Enhancements or major fixes.<br />
<br />
===Streamline checksum verification===<br />
<br />
This enhancement de-duplicates checksum verification in Archivematica, which helps to improve the performance of Archivematica in processing large transfers (many files and/or large files). This enhancement includes three changes:<br />
<br />
* Remove the "Verify checksums generated on ingest" micro-service<br />
* Enhance the "Verify AIP" micro-service to bulk query the database for transfer-generated checksums and then verify that they match what is documented in the bag-generated manifest-<ALGORITHM>.txt.<br />
* Have "Verify AIP" create an AIP-level "fixity check" PREMIS:EVENT that it can pass to the Storage Service, which will document this verification in the pointer file.<br />
<br />
This should not impact regular workflows, but it is worth noting that there is no AIP-level fixity check PREMIS event for uncompressed AIPs, which don't have pointer files. For uncompressed AIPs, there are still object-level fixity events in place. Note that there is an issue in the Archivematica Issues repository regarding this note - [https://github.com/artefactual/archivematica-storage-service/issues/324 Problem: uncompressed AIPs need pointer files #32]<br />
<br />
This work was sponsored by Columbia University Library. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/918 918]<br />
<br />
===Indexing can be enabled/disabled for Transfers and/or Archival Storage===<br />
<br />
Previously, the ElasticSearch index feature could be disabled globally as a scalability measure since indexing consumes a lot of resources. However, this also disabled Backlog and Appraisal features (which also uses indexing) and which some users still wanted to access. As of release 1.8, Archivematica can be deployed to run with indexing enabled just for Transfers (Backlog and Appraisal enabled), just for Archival Storage (Backlog and Appraisal disabled), for both indexes, or for none.<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1172 1172]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/admin-manual/installation-setup/installation/installation/#elasticsearch Installation > Elasticsearch]<br />
<br />
===Configure email settings===<br />
<br />
This change improves the ways that the email client in Archivematica can be configured, including allowing an administrator to set the sender email address for emails sent by Archivematica (i.e. normalization reports, failure reports) to comply with local IT requirements.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1128 1128]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/admin-manual/installation-setup/customization/customization/#email-notification-configuration Email notification configuration]<br />
<br />
===Download processing configuration and reset to default===<br />
<br />
Previous versions of Archivematica introduced the ability to add custom processing configurations, but users had to retrieve the custom configuration file via the command line to use it. There is now a download button on Administration > Processing configuration so that you can download the processing config from the user interface.<br />
<br />
You can also reset a processing configuration to the installation pre-set by clicking on the new reset button on Administration > Processing configuration.<br />
<br />
The documentation for using a custom processing configuration has also been updated.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1138 1138], [https://github.com/artefactual/archivematica/issues/800 800]<br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration (user manual)], [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/customization/dashboard-config/#processing-configuration Processing configuration (administrator manual)], [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/customization/dashboard-config/#using-a-custom-processing-configuration-file Using a custom processing configuration file]<br />
<br />
===MCP batching for scalability & performance===<br />
<br />
This feature refactors how tasks are scheduled, executed & managed within Archivematica, by grouping tasks into batches. It introduces processing efficiencies that significantly decrease the processing power and time required to complete Transfer and Ingest. It includes new configuration options to further optimize processing efficiency for particular types of Transfers (e.g. few large files vs. many small files) and for different deployment patterns (e.g. installing components across multiple machines). <br />
<br />
This feature does not impact the functionality or appearance of Archivematica.<br />
<br />
This work was sponsored by Jisc. Thank you! <br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/938 938]<br />
* Documentation: Scaling Archivematica [update with link when PR 182 is merged];<br />
<br />
===Binder integration improvements===<br />
<br />
Archivematica has had an integration with [https://binder.readthedocs.io/en/latest/user-manual/overview/intro.html Binder] for several years. Binder is an open-source web application for managing time-based media and born-digital artworks that also depends on TMS.<br />
<br />
Since Binder is built off of [https://www.accesstomemory.org/ AtoM], much of the integration configuration was repurposed from the AtoM integration. Archivematica 1.8 makes it explicit, for example, that the job "DIP Upload to AtoM" is actually "DIP Upload to AtoM/Binder". In the Administration tab, the configuration section for AtoM has also been renamed to include Binder.<br />
<br />
Enhancing the Binder integration itself, Archivematica's transfer tab now includes an "Access system ID" box. This allows users to pre-populate an access system ID for AtoM or Binder, so that DIPs can be automatically uploaded without having to stop at the Upload DIP microservice. Users can still use the Upload DIP popup if desired.<br />
<br />
Finally, we've added documentation on using Binder with Archivematica.<br />
<br />
This work was sponsored by Tate. Thank you!<br />
<br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/integrations/integrations/#binder-integration Binder integration], [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/integrations/binder-setup/#binder-setup Using Binder with Archivematica], [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/access/access/#upload-a-dip-to-binder Upload a DIP to Binder]<br />
* Issues: [https://github.com/archivematica/Issues/issues/23 23]<br />
<br />
===File format identification updates===<br />
<br />
Archivematica 1.8 is now up to date with PRONOM v.94! For more information on new data added to PRONOM, check the [http://www.nationalarchives.gov.uk/aboutapps/pronom/release-notes.xml PRONOM release notes].<br />
<br />
This work was sponsored by the Denver Art Museum. Thank you!<br />
<br />
==Fixed==<br />
<br />
* [https://github.com/archivematica/Issues/issues/16 ASCII codes can't decode when the filename contains a backtick]<br />
* [https://github.com/archivematica/Issues/issues/42 AIP re-ingest fails]<br />
* [https://github.com/archivematica/Issues/issues/43 PREMIS events from previous transfers are re-appearing]<br />
* [https://github.com/artefactual/archivematica/issues/1132 Metadata reingest fails when dc:type is null]<br />
* [https://github.com/archivematica/Issues/issues/46 Use 7-zip without compression (Copy) mode]<br />
* [https://github.com/archivematica/Issues/issues/69 Cannot store AIP in DSpace due to file extension returned]<br />
* [https://github.com/archivematica/Issues/issues/123 DSpace REST login error in SS]<br />
* [https://github.com/archivematica/Issues/issues/124 Unable to edit DSpace REST Space settings in SS]<br />
* [https://github.com/artefactual/archivematica-storage-service/issues/391 Packages cannot be stored in DSpace via its REST API]<br />
* [https://github.com/archivematica/Issues/issues/140 Metadata added before "Approve Transfer" disappears]<br />
* [https://github.com/archivematica/Issues/issues/173 Generate AIP METS fails for bag SIPs if bag-info.txt has multiple instances of the same label]<br />
* [https://github.com/artefactual/archivematica/issues/1104 Zip files with diacritic characters are failing to extract]<br />
* [https://github.com/archivematica/Issues/issues/220 restructureBagForComplianceFileUUIDsAssigned needs to create intermediate directories for Zipped bag transfers] - '''Community contribution''' by Hillel Arnold. Thank you!<br />
* [https://github.com/artefactual/archivematica/issues/1050 Ingest fails if Archivematica isn't connected to the Internet]<br />
<br />
==Upgraded tools and dependencies==<br />
<br />
* Fido has been upgraded to version 1.3.12<br />
* Siegfried has been upgraded to version 1.7.10<br />
* FITS has been upgraded to version 1.1.0<br />
<br />
==End of life dependencies==<br />
<br />
===Archivists' Toolkit integration===<br />
<br />
Archivists' Toolkit has been deprecated since 2013. The Archivists' Toolkit DIP upload feature has not had active development or testing since then. There are no plans to start testing or to fix any problems with the feature. As a result, there is a [https://github.com/archivematica/Issues/issues/174 proposal deprecate this feature in Archivematica 1.9]. Community response is welcome via a comment on the issue in GitHub.</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_1.8_and_Storage_Service_0.13_release_notes&diff=12735Archivematica 1.8 and Storage Service 0.13 release notes2018-10-25T19:49:49Z<p>Mcurran: /* Fixed */</p>
<hr />
<div>[[Main_Page|Home]] > [[Release_Notes|Release Notes]] > Major release notes template<br />
<br />
'''Work in progress'''<br />
<br />
==Supported environments==<br />
<br />
Link to installation instructions.<br />
<br />
Specify supported environments.<br />
<br />
Make special note of any changes to supported environment.<br />
<br />
==Added==<br />
<br />
===Dataverse integration===<br />
<br />
Archivematica can now be configured to use a [https://dataverse.org/ Dataverse] research data repository as a transfer source location. Dataverse transfer source locations can be configured to display all available datasets or a subset of them. Datasets are retrieved directly using the Dataverse API and processed using a new “Dataverse” transfer type. New dataverse specific processing includes:<br />
<br />
* fixity checking using checksums generated by dataverse<br />
* retrieval of derivative and metadata files associated with tabular data files<br />
* creation of a Dataverse METS file describing the dataset as retrieved from Dataverse<br />
* Dataverse metadata included in the AIP METS<br />
<br />
Some advanced or more complex use cases are not fully supported, such as handling of datasets with restricted files, versioning of datasets and reingest of datasets. For a full list of known issues and enhancement ideas, refer to the [https://github.com/archivematica/Issues/labels/OCUL%3A%20AM-Dataverse Archivematica issues repository using Dataverse label] and the [https://wiki.archivematica.org/Dataverse Archivematica Wiki]. <br />
<br />
This work was sponsored by [https://scholarsportal.info/ Scholars Portal], a service of the Ontario Council of University Libraries (OCUL). Thank you!<br />
<br />
* Issue: See [https://waffle.io/artefactual/archivematica?label=OCUL:%20AM-Dataverse waffle board] for all issues with the Dataverse label. <br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/transfer/dataverse/ Dataverse Integration]<br />
<br />
===Processing configuration reset and download buttons===<br />
<br />
A new installation of Archivematica comes with a pre-set processing configuration called "default", and a second one (used only in Jisc workflows) called "automated". In testing, users are encouraged to change the configurations to suit their workflows, but may need to reset the configuration to the installation pre-sets. A reset button has been added so that users can easily change the default and automated processing configurations back to their installation pre-sets.<br />
<br />
The second part of this feature is the addition of a download button for the processing configuration files. If you create a custom processing configuration, you can download the resulting processingMCP.xml file using the button and then include it at the top level of your transfer. Archivematica will then use this to automate your transfer selections, rather than the default configuration.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1138 #1138]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration documentation]<br />
<br />
===Public URL===<br />
<br />
Archivematica now has a concept of a public URL in the general configuration. Archivematica usually registers itself with the Storage Service, but if you have deployed Archivematica in an environment where the URL or IP address changes frequently (i.e. in some Docker environments) this can cause issues. In these types of environments, users can now declare a stable public URL that Archivematica can use to register with the Storage Service.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1140 1140]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/admin-manual/installation-setup/customization/dashboard-config/#admin-dashboard-general General configuration]<br />
<br />
==Changed==<br />
<br />
Enhancements or major fixes.<br />
<br />
===Streamline checksum verification===<br />
<br />
This enhancement de-duplicates checksum verification in Archivematica, which helps to improve the performance of Archivematica in processing large transfers (many files and/or large files). This enhancement includes three changes:<br />
<br />
* Remove the "Verify checksums generated on ingest" micro-service<br />
* Enhance the "Verify AIP" micro-service to bulk query the database for transfer-generated checksums and then verify that they match what is documented in the bag-generated manifest-<ALGORITHM>.txt.<br />
* Have "Verify AIP" create an AIP-level "fixity check" PREMIS:EVENT that it can pass to the Storage Service, which will document this verification in the pointer file.<br />
<br />
This should not impact regular workflows, but it is worth noting that there is no AIP-level fixity check PREMIS event for uncompressed AIPs, which don't have pointer files. For uncompressed AIPs, there are still object-level fixity events in place. Note that there is an issue in the Archivematica Issues repository regarding this note - [https://github.com/artefactual/archivematica-storage-service/issues/324 Problem: uncompressed AIPs need pointer files #32]<br />
<br />
This work was sponsored by Columbia University Library. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/918 918]<br />
<br />
===Indexing can be enabled/disabled for Transfers and/or Archival Storage===<br />
<br />
Previously, the ElasticSearch index feature could be disabled globally as a scalability measure since indexing consumes a lot of resources. However, this also disabled Backlog and Appraisal features (which also uses indexing) and which some users still wanted to access. As of release 1.8, Archivematica can be deployed to run with indexing enabled just for Transfers (Backlog and Appraisal enabled), just for Archival Storage (Backlog and Appraisal disabled), for both indexes, or for none.<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1172 1172]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/admin-manual/installation-setup/installation/installation/#elasticsearch Installation > Elasticsearch]<br />
<br />
===Configure email settings===<br />
<br />
This change improves the ways that the email client in Archivematica can be configured, including allowing an administrator to set the sender email address for emails sent by Archivematica (i.e. normalization reports, failure reports) to comply with local IT requirements.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1128 1128]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/admin-manual/installation-setup/customization/customization/#email-notification-configuration Email notification configuration]<br />
<br />
===Download processing configuration and reset to default===<br />
<br />
Previous versions of Archivematica introduced the ability to add custom processing configurations, but users had to retrieve the custom configuration file via the command line to use it. There is now a download button on Administration > Processing configuration so that you can download the processing config from the user interface.<br />
<br />
You can also reset a processing configuration to the installation pre-set by clicking on the new reset button on Administration > Processing configuration.<br />
<br />
The documentation for using a custom processing configuration has also been updated.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1138 1138], [https://github.com/artefactual/archivematica/issues/800 800]<br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration (user manual)], [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/customization/dashboard-config/#processing-configuration Processing configuration (administrator manual)], [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/customization/dashboard-config/#using-a-custom-processing-configuration-file Using a custom processing configuration file]<br />
<br />
===MCP batching for scalability & performance===<br />
<br />
This feature refactors how tasks are scheduled, executed & managed within Archivematica, by grouping tasks into batches. It introduces processing efficiencies that significantly decrease the processing power and time required to complete Transfer and Ingest. It includes new configuration options to further optimize processing efficiency for particular types of Transfers (e.g. few large files vs. many small files) and for different deployment patterns (e.g. installing components across multiple machines). <br />
<br />
This feature does not impact the functionality or appearance of Archivematica.<br />
<br />
This work was sponsored by Jisc. Thank you! <br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/938 938]<br />
* Documentation: Scaling Archivematica [update with link when PR 182 is merged];<br />
<br />
===Binder integration improvements===<br />
<br />
Archivematica has had an integration with [https://binder.readthedocs.io/en/latest/user-manual/overview/intro.html Binder] for several years. Binder is an open-source web application for managing time-based media and born-digital artworks that also depends on TMS.<br />
<br />
Since Binder is built off of [https://www.accesstomemory.org/ AtoM], much of the integration configuration was repurposed from the AtoM integration. Archivematica 1.8 makes it explicit, for example, that the job "DIP Upload to AtoM" is actually "DIP Upload to AtoM/Binder". In the Administration tab, the configuration section for AtoM has also been renamed to include Binder.<br />
<br />
Enhancing the Binder integration itself, Archivematica's transfer tab now includes an "Access system ID" box. This allows users to pre-populate an access system ID for AtoM or Binder, so that DIPs can be automatically uploaded without having to stop at the Upload DIP microservice. Users can still use the Upload DIP popup if desired.<br />
<br />
Finally, we've added documentation on using Binder with Archivematica.<br />
<br />
This work was sponsored by Tate. Thank you!<br />
<br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/integrations/integrations/#binder-integration Binder integration], [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/integrations/binder-setup/#binder-setup Using Binder with Archivematica], [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/access/access/#upload-a-dip-to-binder Upload a DIP to Binder]<br />
* Issues: [https://github.com/archivematica/Issues/issues/23 23]<br />
<br />
===File format identification updates===<br />
<br />
Archivematica 1.8 is now up to date with PRONOM v.94! For more information on new data added to PRONOM, check the [http://www.nationalarchives.gov.uk/aboutapps/pronom/release-notes.xml PRONOM release notes].<br />
<br />
This work was sponsored by the Denver Art Museum. Thank you!<br />
<br />
==Fixed==<br />
<br />
* [https://github.com/archivematica/Issues/issues/16 ASCII codes can't decode when the filename contains a backtick]<br />
* [https://github.com/archivematica/Issues/issues/42 AIP re-ingest fails]<br />
* [https://github.com/archivematica/Issues/issues/43 PREMIS events from previous transfers are re-appearing]<br />
* [https://github.com/artefactual/archivematica/issues/1132 Metadata reingest fails when dc:type is null]<br />
* [https://github.com/archivematica/Issues/issues/46 Use 7-zip without compression (Copy) mode]<br />
* [https://github.com/archivematica/Issues/issues/69 Cannot store AIP in DSpace due to file extension returned]<br />
* [https://github.com/archivematica/Issues/issues/123 DSpace REST login error in SS]<br />
* [https://github.com/archivematica/Issues/issues/124 Unable to edit DSpace REST Space settings in SS]<br />
* [https://github.com/archivematica/Issues/issues/140 Metadata added before "Approve Transfer" disappears]<br />
* [https://github.com/archivematica/Issues/issues/173 Generate AIP METS fails for bag SIPs if bag-info.txt has multiple instances of the same label]<br />
* [https://github.com/artefactual/archivematica/issues/1104 Zip files with diacritic characters are failing to extract]<br />
* [https://github.com/archivematica/Issues/issues/220 restructureBagForComplianceFileUUIDsAssigned needs to create intermediate directories for Zipped bag transfers] - '''Community contribution''' by Hillel Arnold. Thank you!<br />
* [https://github.com/artefactual/archivematica/issues/1050 Ingest fails if Archivematica isn't connected to the Internet]<br />
<br />
==Upgraded tools and dependencies==<br />
<br />
* Fido has been upgraded to version 1.3.12<br />
* Siegfried has been upgraded to version 1.7.10<br />
* FITS has been upgraded to version 1.1.0<br />
<br />
==End of life dependencies==<br />
<br />
===Archivists' Toolkit integration===<br />
<br />
Archivists' Toolkit has been deprecated since 2013. The Archivists' Toolkit DIP upload feature has not had active development or testing since then. There are no plans to start testing or to fix any problems with the feature. As a result, there is a [https://github.com/archivematica/Issues/issues/174 proposal deprecate this feature in Archivematica 1.9]. Community response is welcome via a comment on the issue in GitHub.</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_1.8_and_Storage_Service_0.13_release_notes&diff=12734Archivematica 1.8 and Storage Service 0.13 release notes2018-10-25T19:47:12Z<p>Mcurran: /* Fixed */</p>
<hr />
<div>[[Main_Page|Home]] > [[Release_Notes|Release Notes]] > Major release notes template<br />
<br />
'''Work in progress'''<br />
<br />
==Supported environments==<br />
<br />
Link to installation instructions.<br />
<br />
Specify supported environments.<br />
<br />
Make special note of any changes to supported environment.<br />
<br />
==Added==<br />
<br />
===Dataverse integration===<br />
<br />
Archivematica can now be configured to use a [https://dataverse.org/ Dataverse] research data repository as a transfer source location. Dataverse transfer source locations can be configured to display all available datasets or a subset of them. Datasets are retrieved directly using the Dataverse API and processed using a new “Dataverse” transfer type. New dataverse specific processing includes:<br />
<br />
* fixity checking using checksums generated by dataverse<br />
* retrieval of derivative and metadata files associated with tabular data files<br />
* creation of a Dataverse METS file describing the dataset as retrieved from Dataverse<br />
* Dataverse metadata included in the AIP METS<br />
<br />
Some advanced or more complex use cases are not fully supported, such as handling of datasets with restricted files, versioning of datasets and reingest of datasets. For a full list of known issues and enhancement ideas, refer to the [https://github.com/archivematica/Issues/labels/OCUL%3A%20AM-Dataverse Archivematica issues repository using Dataverse label] and the [https://wiki.archivematica.org/Dataverse Archivematica Wiki]. <br />
<br />
This work was sponsored by [https://scholarsportal.info/ Scholars Portal], a service of the Ontario Council of University Libraries (OCUL). Thank you!<br />
<br />
* Issue: See [https://waffle.io/artefactual/archivematica?label=OCUL:%20AM-Dataverse waffle board] for all issues with the Dataverse label. <br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/transfer/dataverse/ Dataverse Integration]<br />
<br />
===Processing configuration reset and download buttons===<br />
<br />
A new installation of Archivematica comes with a pre-set processing configuration called "default", and a second one (used only in Jisc workflows) called "automated". In testing, users are encouraged to change the configurations to suit their workflows, but may need to reset the configuration to the installation pre-sets. A reset button has been added so that users can easily change the default and automated processing configurations back to their installation pre-sets.<br />
<br />
The second part of this feature is the addition of a download button for the processing configuration files. If you create a custom processing configuration, you can download the resulting processingMCP.xml file using the button and then include it at the top level of your transfer. Archivematica will then use this to automate your transfer selections, rather than the default configuration.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1138 #1138]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration documentation]<br />
<br />
===Public URL===<br />
<br />
Archivematica now has a concept of a public URL in the general configuration. Archivematica usually registers itself with the Storage Service, but if you have deployed Archivematica in an environment where the URL or IP address changes frequently (i.e. in some Docker environments) this can cause issues. In these types of environments, users can now declare a stable public URL that Archivematica can use to register with the Storage Service.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1140 1140]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/admin-manual/installation-setup/customization/dashboard-config/#admin-dashboard-general General configuration]<br />
<br />
==Changed==<br />
<br />
Enhancements or major fixes.<br />
<br />
===Streamline checksum verification===<br />
<br />
This enhancement de-duplicates checksum verification in Archivematica, which helps to improve the performance of Archivematica in processing large transfers (many files and/or large files). This enhancement includes three changes:<br />
<br />
* Remove the "Verify checksums generated on ingest" micro-service<br />
* Enhance the "Verify AIP" micro-service to bulk query the database for transfer-generated checksums and then verify that they match what is documented in the bag-generated manifest-<ALGORITHM>.txt.<br />
* Have "Verify AIP" create an AIP-level "fixity check" PREMIS:EVENT that it can pass to the Storage Service, which will document this verification in the pointer file.<br />
<br />
This should not impact regular workflows, but it is worth noting that there is no AIP-level fixity check PREMIS event for uncompressed AIPs, which don't have pointer files. For uncompressed AIPs, there are still object-level fixity events in place. Note that there is an issue in the Archivematica Issues repository regarding this note - [https://github.com/artefactual/archivematica-storage-service/issues/324 Problem: uncompressed AIPs need pointer files #32]<br />
<br />
This work was sponsored by Columbia University Library. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/918 918]<br />
<br />
===Indexing can be enabled/disabled for Transfers and/or Archival Storage===<br />
<br />
Previously, the ElasticSearch index feature could be disabled globally as a scalability measure since indexing consumes a lot of resources. However, this also disabled Backlog and Appraisal features (which also uses indexing) and which some users still wanted to access. As of release 1.8, Archivematica can be deployed to run with indexing enabled just for Transfers (Backlog and Appraisal enabled), just for Archival Storage (Backlog and Appraisal disabled), for both indexes, or for none.<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1172 1172]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/admin-manual/installation-setup/installation/installation/#elasticsearch Installation > Elasticsearch]<br />
<br />
===Configure email settings===<br />
<br />
This change improves the ways that the email client in Archivematica can be configured, including allowing an administrator to set the sender email address for emails sent by Archivematica (i.e. normalization reports, failure reports) to comply with local IT requirements.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1128 1128]<br />
* Documentation: [https://www.archivematica.org/docs/archivematica-1.8/admin-manual/installation-setup/customization/customization/#email-notification-configuration Email notification configuration]<br />
<br />
===Download processing configuration and reset to default===<br />
<br />
Previous versions of Archivematica introduced the ability to add custom processing configurations, but users had to retrieve the custom configuration file via the command line to use it. There is now a download button on Administration > Processing configuration so that you can download the processing config from the user interface.<br />
<br />
You can also reset a processing configuration to the installation pre-set by clicking on the new reset button on Administration > Processing configuration.<br />
<br />
The documentation for using a custom processing configuration has also been updated.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1138 1138], [https://github.com/artefactual/archivematica/issues/800 800]<br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration (user manual)], [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/customization/dashboard-config/#processing-configuration Processing configuration (administrator manual)], [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/customization/dashboard-config/#using-a-custom-processing-configuration-file Using a custom processing configuration file]<br />
<br />
===MCP batching for scalability & performance===<br />
<br />
This feature refactors how tasks are scheduled, executed & managed within Archivematica, by grouping tasks into batches. It introduces processing efficiencies that significantly decrease the processing power and time required to complete Transfer and Ingest. It includes new configuration options to further optimize processing efficiency for particular types of Transfers (e.g. few large files vs. many small files) and for different deployment patterns (e.g. installing components across multiple machines). <br />
<br />
This feature does not impact the functionality or appearance of Archivematica.<br />
<br />
This work was sponsored by Jisc. Thank you! <br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/938 938]<br />
* Documentation: Scaling Archivematica [update with link when PR 182 is merged];<br />
<br />
===Binder integration improvements===<br />
<br />
Archivematica has had an integration with [https://binder.readthedocs.io/en/latest/user-manual/overview/intro.html Binder] for several years. Binder is an open-source web application for managing time-based media and born-digital artworks that also depends on TMS.<br />
<br />
Since Binder is built off of [https://www.accesstomemory.org/ AtoM], much of the integration configuration was repurposed from the AtoM integration. Archivematica 1.8 makes it explicit, for example, that the job "DIP Upload to AtoM" is actually "DIP Upload to AtoM/Binder". In the Administration tab, the configuration section for AtoM has also been renamed to include Binder.<br />
<br />
Enhancing the Binder integration itself, Archivematica's transfer tab now includes an "Access system ID" box. This allows users to pre-populate an access system ID for AtoM or Binder, so that DIPs can be automatically uploaded without having to stop at the Upload DIP microservice. Users can still use the Upload DIP popup if desired.<br />
<br />
Finally, we've added documentation on using Binder with Archivematica.<br />
<br />
This work was sponsored by Tate. Thank you!<br />
<br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/integrations/integrations/#binder-integration Binder integration], [https://www.archivematica.org/en/docs/archivematica-1.8/admin-manual/installation-setup/integrations/binder-setup/#binder-setup Using Binder with Archivematica], [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/access/access/#upload-a-dip-to-binder Upload a DIP to Binder]<br />
* Issues: [https://github.com/archivematica/Issues/issues/23 23]<br />
<br />
===File format identification updates===<br />
<br />
Archivematica 1.8 is now up to date with PRONOM v.94! For more information on new data added to PRONOM, check the [http://www.nationalarchives.gov.uk/aboutapps/pronom/release-notes.xml PRONOM release notes].<br />
<br />
This work was sponsored by the Denver Art Museum. Thank you!<br />
<br />
==Fixed==<br />
<br />
* [https://github.com/archivematica/Issues/issues/16 ASCII codes can't decode when the filename contains a backtick]<br />
* [https://github.com/archivematica/Issues/issues/42 AIP re-ingest fails]<br />
* [https://github.com/archivematica/Issues/issues/43 PREMIS events from previous transfers are re-appearing]<br />
* [https://github.com/artefactual/archivematica/issues/1132 Metadata reingest fails when dc:type is null]<br />
* [https://github.com/archivematica/Issues/issues/46 Use 7-zip without compression (Copy) mode]<br />
* [https://github.com/archivematica/Issues/issues/69 Problem: cannot store AIP in DSpace due to file extension returned]<br />
* [https://github.com/archivematica/Issues/issues/123 DSpace REST login error in SS]<br />
* [https://github.com/archivematica/Issues/issues/124 Unable to edit DSpace REST Space settings in SS]<br />
* [https://github.com/archivematica/Issues/issues/140 Metadata added before "Approve Transfer" disappears]<br />
* [https://github.com/archivematica/Issues/issues/173 Generate AIP METS fails for bag SIPs if bag-info.txt has multiple instances of the same label]<br />
* [https://github.com/artefactual/archivematica/issues/1104 Zip files with diacritic characters are failing to extract]<br />
* [https://github.com/archivematica/Issues/issues/220 restructureBagForComplianceFileUUIDsAssigned needs to create intermediate directories for Zipped bag transfers] - '''Community contribution''' by Hillel Arnold. Thank you!<br />
* [https://github.com/artefactual/archivematica/issues/1050 Ingest fails if Archivematica isn't connected to the Internet]<br />
<br />
==Upgraded tools and dependencies==<br />
<br />
* Fido has been upgraded to version 1.3.12<br />
* Siegfried has been upgraded to version 1.7.10<br />
* FITS has been upgraded to version 1.1.0<br />
<br />
==End of life dependencies==<br />
<br />
===Archivists' Toolkit integration===<br />
<br />
Archivists' Toolkit has been deprecated since 2013. The Archivists' Toolkit DIP upload feature has not had active development or testing since then. There are no plans to start testing or to fix any problems with the feature. As a result, there is a [https://github.com/archivematica/Issues/issues/174 proposal deprecate this feature in Archivematica 1.9]. Community response is welcome via a comment on the issue in GitHub.</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_1.8_and_Storage_Service_0.13_release_notes&diff=12705Archivematica 1.8 and Storage Service 0.13 release notes2018-10-16T04:00:18Z<p>Mcurran: /* Fixed */</p>
<hr />
<div>[[Main_Page|Home]] > [[Release_Notes|Release Notes]] > Major release notes template<br />
<br />
'''Work in progress'''<br />
<br />
==Supported environments==<br />
<br />
Link to installation instructions.<br />
<br />
Specify supported environments.<br />
<br />
Make special note of any changes to supported environment.<br />
<br />
==Added==<br />
<br />
Describe new features.<br />
<br />
===New feature template===<br />
<br />
This is a description of this amazing feature! Here's why it's a net benefit to the project and the community. Also included are any special notes, like if it's a beta feature.<br />
<br />
This work was sponsored by some amazing institution. Thank you!<br />
<br />
* Documentation: link<br />
* Pull requests: link<br />
<br />
===Processing configuration reset and download buttons===<br />
<br />
A new installation of Archivematica comes with a pre-set processing configuration called "default", and a second one (used only in Jisc workflows) called "automated". In testing, users are encouraged to change the configurations to suit their workflows, but may need to reset the configuration to the installation pre-sets. A reset button has been added so that users can easily change the default and automated processing configurations back to their installation pre-sets.<br />
<br />
The second part of this feature is the addition of a download button for the processing configuration files. If you create a custom processing configuration, you can download the resulting processingMCP.xml file using the button and then include it at the top level of your transfer. Archivematica will then use this to automate your transfer selections, rather than the default configuration.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration documentation]<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1138 #1138]<br />
<br />
==Changed==<br />
<br />
Describe enhancements or major fixes.<br />
<br />
===Streamline checksum verification===<br />
<br />
This enhancement de-duplicates checksum verification in Archivematica, which helps to improve the performance of Archivematica in processing large transfers (many files and/or large files). This enhancement includes three changes:<br />
<br />
* Remove the "Verify checksums generated on ingest" micro-service<br />
* Enhance the "Verify AIP" micro-service to bulk query the database for transfer-generated checksums and then verify that they match what is documented in the bag-generated manifest-<ALGORITHM>.txt.<br />
* Have "Verify AIP" create an AIP-level "fixity check" PREMIS:EVENT that it can pass to the Storage Service, which will document this verification in the pointer file.<br />
<br />
This should not impact regular workflows, but it is worth noting that there is no AIP-level fixity check PREMIS event for uncompressed AIPs, which don't have pointer files. For uncompressed AIPs, there are still object-level fixity events in place. Note that there is an issue in the Archivematica Issues repository regarding this note - [https://github.com/artefactual/archivematica-storage-service/issues/324 Problem: uncompressed AIPs need pointer files #32]<br />
<br />
This work was sponsored by Columbia University Library. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/918 #918]<br />
* Pull requests: [https://github.com/artefactual/archivematica/pull/1012 PR 1012]<br />
<br />
===File format identification updates===<br />
<br />
Archivematica 1.8 is now up to date with PRONOM v.94! For more information on new data added to PRONOM, check the [http://www.nationalarchives.gov.uk/aboutapps/pronom/release-notes.xml PRONOM release notes].<br />
<br />
This work was sponsored by the Denver Art Museum. Thank you!<br />
<br />
===Indexing can be enabled/disabled for Transfers and/or Archival Storage===<br />
Previously, the ElasticSearch index feature could be disabled globally as a scalability measure since indexing consumes a lot of resources. However, this also disabled Backlog and Appraisal features (which also uses indexing) and which some users still wanted to access. As of release 1.8, Archivematica can be deployed to run with indexing enabled just for Transfers (Backlog and Appraisal enabled), just for Archival Storage (Backlog and Appraisal disabled), for both indexes, or for none.<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1172 1172]<br />
<br />
==Fixed==<br />
<br />
List bugfixes with a link to the Github issue.<br />
<br />
* Bugfix 1: ASCII codes can't decode when the filename contains a backtick https://github.com/archivematica/Issues/issues/16<br />
* Bugfix 2: AIP re-ingest fails. https://github.com/archivematica/Issues/issues/42<br />
* Bugfix 3: PREMIS events from previous transfers are re-appearing https://github.com/archivematica/Issues/issues/43<br />
* Bugfix 4: Metadata reingest fails when dc:type is null https://github.com/artefactual/archivematica/issues/1132<br />
* Bugfix 5: Use 7-zip without compression (Copy) mode https://github.com/archivematica/Issues/issues/46<br />
* Bugfix 6: Metadata added before "Approve Transfer" disappears https://github.com/archivematica/Issues/issues/140<br />
* Bugfix 7: Generate AIP METS fails for bag SIPs if bag-info.txt has multiple instances of the same label https://github.com/archivematica/Issues/issues/173<br />
* Bugfix 8: Zip files with diacritic characters are failing to extract https://github.com/artefactual/archivematica/issues/1104<br />
* Bugfix 9: DSpace REST login error in SS https://github.com/archivematica/Issues/issues/123<br />
* Bugfix 10: Unable to edit DSpace REST Space settings in SS https://github.com/archivematica/Issues/issues/124<br />
<br />
==Upgraded tools and dependencies==<br />
<br />
* Tool has been updated to version X.<br />
* Fido has been upgraded to version 1.3.12<br />
* Siegfried has been upgraded to version 1.7.10<br />
<br />
==End of life dependencies==<br />
<br />
===Archivists' Toolkit integration===<br />
<br />
Archivists' Toolkit has been deprecated since 2013. The Archivists' Toolkit DIP upload feature has not had active development or testing since then. There are no plans to start testing or to fix any problems with the feature. As a result, there is a [https://github.com/archivematica/Issues/issues/174 proposal deprecate this feature in Archivematica 1.9]. Community response is welcome via a comment on the issue in GitHub.</div>Mcurranhttps://wiki.archivematica.org/index.php?title=Archivematica_1.8_and_Storage_Service_0.13_release_notes&diff=12704Archivematica 1.8 and Storage Service 0.13 release notes2018-10-16T02:59:24Z<p>Mcurran: /* Fixed */</p>
<hr />
<div>[[Main_Page|Home]] > [[Release_Notes|Release Notes]] > Major release notes template<br />
<br />
'''Work in progress'''<br />
<br />
==Supported environments==<br />
<br />
Link to installation instructions.<br />
<br />
Specify supported environments.<br />
<br />
Make special note of any changes to supported environment.<br />
<br />
==Added==<br />
<br />
Describe new features.<br />
<br />
===New feature template===<br />
<br />
This is a description of this amazing feature! Here's why it's a net benefit to the project and the community. Also included are any special notes, like if it's a beta feature.<br />
<br />
This work was sponsored by some amazing institution. Thank you!<br />
<br />
* Documentation: link<br />
* Pull requests: link<br />
<br />
===Processing configuration reset and download buttons===<br />
<br />
A new installation of Archivematica comes with a pre-set processing configuration called "default", and a second one (used only in Jisc workflows) called "automated". In testing, users are encouraged to change the configurations to suit their workflows, but may need to reset the configuration to the installation pre-sets. A reset button has been added so that users can easily change the default and automated processing configurations back to their installation pre-sets.<br />
<br />
The second part of this feature is the addition of a download button for the processing configuration files. If you create a custom processing configuration, you can download the resulting processingMCP.xml file using the button and then include it at the top level of your transfer. Archivematica will then use this to automate your transfer selections, rather than the default configuration.<br />
<br />
This work was sponsored by Jisc. Thank you!<br />
<br />
* Documentation: [https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/administer/dashboard-admin/#processing-configuration Processing configuration documentation]<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1138 #1138]<br />
<br />
==Changed==<br />
<br />
Describe enhancements or major fixes.<br />
<br />
===Streamline checksum verification===<br />
<br />
This enhancement de-duplicates checksum verification in Archivematica, which helps to improve the performance of Archivematica in processing large transfers (many files and/or large files). This enhancement includes three changes:<br />
<br />
* Remove the "Verify checksums generated on ingest" micro-service<br />
* Enhance the "Verify AIP" micro-service to bulk query the database for transfer-generated checksums and then verify that they match what is documented in the bag-generated manifest-<ALGORITHM>.txt.<br />
* Have "Verify AIP" create an AIP-level "fixity check" PREMIS:EVENT that it can pass to the Storage Service, which will document this verification in the pointer file.<br />
<br />
This should not impact regular workflows, but it is worth noting that there is no AIP-level fixity check PREMIS event for uncompressed AIPs, which don't have pointer files. For uncompressed AIPs, there are still object-level fixity events in place. Note that there is an issue in the Archivematica Issues repository regarding this note - [https://github.com/artefactual/archivematica-storage-service/issues/324 Problem: uncompressed AIPs need pointer files #32]<br />
<br />
This work was sponsored by Columbia University Library. Thank you!<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/918 #918]<br />
* Pull requests: [https://github.com/artefactual/archivematica/pull/1012 PR 1012]<br />
<br />
===File format identification updates===<br />
<br />
Archivematica 1.8 is now up to date with PRONOM v.94! For more information on new data added to PRONOM, check the [http://www.nationalarchives.gov.uk/aboutapps/pronom/release-notes.xml PRONOM release notes].<br />
<br />
This work was sponsored by the Denver Art Museum. Thank you!<br />
<br />
===Indexing can be enabled/disabled for Transfers and/or Archival Storage===<br />
Previously, the ElasticSearch index feature could be disabled globally as a scalability measure since indexing consumes a lot of resources. However, this also disabled Backlog and Appraisal features (which also uses indexing) and which some users still wanted to access. As of release 1.8, Archivematica can be deployed to run with indexing enabled just for Transfers (Backlog and Appraisal enabled), just for Archival Storage (Backlog and Appraisal disabled), for both indexes, or for none.<br />
<br />
* Issue: [https://github.com/artefactual/archivematica/issues/1172 1172]<br />
<br />
==Fixed==<br />
<br />
List bugfixes with a link to the Github issue.<br />
<br />
* Bugfix 1: ASCII codes can't decode when the filename contains a backtick https://github.com/archivematica/Issues/issues/16<br />
* Bugfix 2: AIP re-ingest fails. https://github.com/archivematica/Issues/issues/42<br />
* Bugfix 3: PREMIS events from previous transfers are re-appearing https://github.com/archivematica/Issues/issues/43<br />
* Bugfix 4: Metadata reingest fails when dc:type is null https://github.com/artefactual/archivematica/issues/1132<br />
* Bugfix 5: Use 7-zip without compression (Copy) mode https://github.com/archivematica/Issues/issues/46<br />
* Bugfix 6: Metadata added before "Approve Transfer" disappears https://github.com/archivematica/Issues/issues/140<br />
* Bugfix 7: Generate AIP METS fails for bag SIPs if bag-info.txt has multiple instances of the same label https://github.com/archivematica/Issues/issues/173<br />
* Bugfix 8: Zip files with diacritic characters are failing to extract https://github.com/artefactual/archivematica/issues/1104<br />
* Bugfix 9: DSpace REST login error in SS https://github.com/archivematica/Issues/issues/123<br />
<br />
==Upgraded tools and dependencies==<br />
<br />
* Tool has been updated to version X.<br />
* Fido has been upgraded to version 1.3.12<br />
* Siegfried has been upgraded to version 1.7.10<br />
<br />
==End of life dependencies==<br />
<br />
===Archivists' Toolkit integration===<br />
<br />
Archivists' Toolkit has been deprecated since 2013. The Archivists' Toolkit DIP upload feature has not had active development or testing since then. There are no plans to start testing or to fix any problems with the feature. As a result, there is a [https://github.com/archivematica/Issues/issues/174 proposal deprecate this feature in Archivematica 1.9]. Community response is welcome via a comment on the issue in GitHub.</div>Mcurran