From 596930ae5b589f3243fc6aa78ee8fb0ed9f8c600 Mon Sep 17 00:00:00 2001 From: Dhwani Patel Date: Thu, 21 Mar 2024 09:51:41 -0600 Subject: [PATCH] Update create space api --- .../api/api-reference-storage-service.rst | 344 +++++++++++++++++- 1 file changed, 339 insertions(+), 5 deletions(-) diff --git a/dev-manual/api/api-reference-storage-service.rst b/dev-manual/api/api-reference-storage-service.rst index 3669395a..5b0e2bbe 100644 --- a/dev-manual/api/api-reference-storage-service.rst +++ b/dev-manual/api/api-reference-storage-service.rst @@ -494,6 +494,7 @@ Example response (JSON): .. literalinclude:: _code/ss_browse_space_path_response.curl +.. _create_space: Create space ^^^^^^^^^^^^ @@ -506,10 +507,9 @@ Create space Request body parameters: -Parameters should contain fields for a new space: See the `Storage Service \ -`_ -documentation for fields relevant to each type of space. Basic fields for a -local file system space are listed below. +Parameters should contain fields for a new space: See +:ref:`Access protocols ` documentation for fields relevant +to each type of space. Basic fields for each Access Protocols are listed below. =================== ========================================================== @@ -520,6 +520,10 @@ local file system space are listed below. ``size`` (Optional) Maximum size allowed for this space. Set to 0 or leave blank for unlimited. +``staging_path`` The absolute path to a staging area. Must be UNIX + filesystem compatible and preferably will be located on + the same filesystem as the path. + =================== ========================================================== Example (to create an S3 space):: @@ -540,13 +544,343 @@ Where payload.json contains:: "endpoint_url": "http://127.0.0.1:12345", "access_key_id": "_Cah4cae1_", "secret_access_key": "_Thu6Ahqu_", - "region": "us-west-2" + "region": "us-west-2", + "bucket": "bucket_name" } .. note:: Endpoint returns all paths base64 encoded. +.. _access-protocols: + +Access protocols +^^^^^^^^^^^^^^^^ + +Archipelago +^^^^^^^^^^^ + +Archipelago is currently supported for AIP Storage locations. +Archipelago is built on the content management system Drupal, +which accepts JSON API calls to create new entities. +Basic fields for Archipelago space are listed in :ref:`Create space ` + +Request body parameters: + +========================= ========================================================== + +``archipelago_url`` The hostname of the Archipelago web instance or IP address + with port, e.g. archipelago.example.com:8443 + +``archipelago_user`` Archipelago username with write access required. + +``archipelago_password`` Archipelago password with write access required. + +========================= ========================================================== + +Arkivum +^^^^^^^ + +Archivematica can use Arkivum’s A-Stor as an access protocol in version 0.7 and higher. +Basic fields for Arkivum space are listed in :ref:`Create space ` + +Request body parameters: + +================== =============================================================== + +``host`` The hostname of the Arkivum web instance or IP address + with port, e.g. arkivum.example.com:8443 + +``remote_user`` Username on the remote machine accessible via passwordless ssh. + +``remote_name`` Name or IP of the remote machine. + +================== =============================================================== + +Dataverse +^^^^^^^^^ + +Dataverse Integration is supported with Archivematica v1.8 (and higher) and +Storage Service v0.13 (and higher). Basic fields for Dataverse space +are listed in :ref:`Create space ` + +Request body parameters: + +===================== =============================================================== + +``host`` The hostname of the Dataverse web instance or IP address + with port, e.g. dataverse.example.com:8443 + +``api_key`` API key for Dataverse instance. + +``agent_name`` A string that will be used in Archivematica METS file to + identify this Dataverse instance as a PREMIS agent, + e.g. My Institution's Dataverse Instance. + +``agent_type`` A string that will be used in Archivematica METS file to + identify the type of PREMIS agent named above, + e.g. organization.Name or IP of the remote machine. + +``agent_identifier`` A string that will be used as an identifier in the Archivematica + METS file to uniquely identify the PREMIS agent named above. + +===================== =============================================================== + +DuraCloud +^^^^^^^^^ + +Archivematica can use DuraCloud as an access protocol for the Storage Service in +version 0.5 and higher. Basic fields for a DuraCloud space are +listed in :ref:`Create space ` + +Request body parameters: + +================== ======================================================================= + +``host`` The hostname of the Duracloud web instance or IP address + with port, e.g. duracloud.example.com:8443 + +``user`` The username for the Archivematica user that you created in DuraCloud. + +``password`` The password for the Archivematica user that you created in DuraCloud. + +``duraspace`` The name of the space within DuraCloud. + +================== ======================================================================= + +DSpace via SWORD2 API +^^^^^^^^^^^^^^^^^^^^^ + +DSpace via SWORD2 locations are currently supported only for AIP Storage locations. +Basic fields for a DSpace are listed in :ref:`Create space ` + +Request body parameters: + +=================== ======================================================================================= + +``sd_iri`` URL of the service document. E.g. ``http://demo.dspace.org/swordv2/servicedocument,`` + where servicedocument is the handle to the community or collection being used + for deposit. + +``user`` A username for the DSpace instance with sufficient permissions to permit + authentication. + +``password`` The password for the Dspace user that you created. + +``metadata_policy`` Use to restrict access to the metadata bitstream. Must be specified as a list of + objects in JSON, e.g. ``[{"action":"READ","groupId":"5","rpType":"TYPE_CUSTOM"}]``. + +``archive_format`` Archive format, e.g. ``ZIP``, ``7z``. + +=================== ======================================================================================= + +DSpace via REST API +^^^^^^^^^^^^^^^^^^^ + +DSpace via REST API locations are supported for both AIP and DIP Storage locations. +Basic fields for a DSpace via REST API space are listed in :ref:`Create space ` + +Request body parameters: + +====================== ===================================================================================== + +``ds_rest_url`` URL to the "REST" webapp. E.g. ``http://localhost:8080/rest/``; for production + systems, this address will be slightly different, such as: + ``https://demo.dspace.org/rest/``. + +``ds_user`` A username for the DSpace instance with sufficient permissions to permit + authentication. + +``ds_password`` The password for the Dspace user that you created. + +``ds_dip_collection`` UUID of default DSpace collection for the DIP to be deposited. + +``ds_aip_collection`` UUID of default DSpace collection for the AIP to be deposited. + +``as_url`` URL to the ArchiveSpace server. E.g.: ``http://sandbox.archivesspace.org/``. + +``as_user`` ArchivesSpace username to authenticate as. + +``as_password`` ArchivesSpace password to authenticate with. + +``as_repository`` Identifier of the default ArchivesSpace repository. + +``as_archival_object`` Identifier of the default ArchivesSpace archival object. + +``upload_to_tsm`` Boolean true or false. Default is false. will attempt to send the AIP to + the Tivoli Storage Manager using command-line client dsmc + +``verify_ssl`` Boolean true or false. Default is true. + +====================== ===================================================================================== + +Fedora via SWORD2 +^^^^^^^^^^^^^^^^^ + +Basic fields for a Fedora space are listed in :ref:`Create space ` + +Request body parameters: + +==================== ================================================== + +``fedora_user`` Fedora user name (for SWORD functionality). + +``fedora_password`` Fedora password (for SWORD functionality). + +``fedora_name`` Name or IP of the remote Fedora machine. + +==================== ================================================== + +GPG encryption on Local Filesystem +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Creating a GPG encryption space will allow users to create encrypted AIPs and +transfers. Basic fields for a local file system space are listed in +:ref:`Create space ` + +Request body parameters: + +========== ================================================ + +``key`` The encryption key to be used for the space. + +========== ================================================ + +Local Filesystem +^^^^^^^^^^^^^^^^ + +Local Filesystem spaces handle storage that is available locally on the +machine running the Storage Service. Basic fields for a local file +system space are listed in :ref:`Create space ` + +LOCKSS +^^^^^^ + +Archivematica can store AIPs in a `LOCKSS`_ network via LOCKSS-O-Matic. +Basic fields for a LOCKSS space are listed in :ref:`Create space ` + +Request body parameters: + +======================== =============================================================== + +``sd_iri`` The URL of the LOCKSS-o-matic service document IRI, + e.g. ``http://lockssomatic.example.org/api/sword/2.0/sd-iri``. + +``content_provider_id`` On-Behalf-Of value when communicating with LOCKSS-o-matic. + +``external_domain`` Base URL for this server that LOCKSS will be able to access. + +``keep_local`` Boolean true or false. Default is true. + +======================== =============================================================== + +NFS +^^^ + +NFS spaces are for NFS exports mounted on the Storage Service server and the +Archivematica pipeline. Basic fields for a NFS space are listed +in :ref:`Create space ` + +Request body parameters: + +==================== ================================================ + +``remote_name`` Name of the NFS server. + +``remote_path`` Path on the NFS server to the export. + +``version`` Type of the filesystem, e.g. ``nfs or nfs4`` + +``manually_mounted`` Boolean true or false. Default is false. + +==================== ================================================ + +Pipeline Local Filesystem +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pipeline Local Filesystems refer to the storage that is local to the +Archivematica pipeline, but remote to the Storage Service. +Basic fields for a Pipeline Local Filesystem space are listed +in :ref:`Create space ` + +Request body parameters: + +======================== ================================================ + +``remote_user`` The username on the remote host. + +``remote_name`` Name or IP of the remote machine. + +``assume_rsync_daemon`` Boolean true or false. Default is false. + +``rsync_password`` The password for the rsync daemon. + +======================== ================================================ + +RClone +^^^^^^ + +Rclone is a command-line program to manage files in cloud storage, and is +available as an access protocol in Storage Service 0.20 and higher. +Basic fields for a Rclone space are listed in :ref:`Create space ` + +Request body parameters: + +================= ================================================================== + +``remote_name`` Remote name for the rclone configuration to use with this Space. + +``container`` Container or bucket name to use in configured remote. + +================= ================================================================== + +Swift +^^^^^^ + +OpenStack's Swift is available as an access protocol in Storage Service 0.7 and +higher. Basic fields for a Swift space are listed in :ref:`Create space ` + +Request body parameters: + +================= ====================================================================== + +``auth_url`` The URL to authenticate against. + +``auth_version`` The OpenStack authentication version. Default is 2. + +``username`` Username to authenticate as. E.g. ``http://example.com:5000/v2.0/`` + +``password`` Password to authenticate with. + +``container`` The name of the Swift container. + +``tenant`` The tenant/account name. + +``region`` The region in Swift. This field is optional. + +================= ====================================================================== + +S3 (Amazon) +^^^^^^^^^^^ + +Amazon S3 is available as an access protocol as of Storage Service version 0.12. +Basic fields for a S3(Amazon) space are listed in :ref:`Create space ` + +Request body parameters: + +====================== =================================================================== + +``endpoint_url`` The URL of the S3 endpoint, e.g. ``https://s3.amazonaws.com``. + +``access_key_id`` The public key generated by S3. + +``secret_access_key`` The secret key generated by S3. + +``region`` The region that the S3 instance uses, e.g. ``us-east-2``. + +``bucket`` The name of the designated S3 Bucket. + +====================== =================================================================== .. _ss-location: