{ "openapi": "3.0.1", "info": { "title": "Archival Storage Gateway API", "contact": { "name": "inQool, a.s.", "url": "https://inqool.cz/", "email": "info@inqool.cz" }, "license": { "name": "GNU GPL v3" }, "version": "v2.0" }, "externalDocs": { "description": "Archival Storage Documentation", "url": "https://frnk.lightcomp.cz/download/cuni-ais/doc/arcstorage/arcstorage.html" }, "servers": [ { "url": "http://localhost:8088", "description": "Generated server url" } ], "security": [ { "basicAuth": [ ] } ], "tags": [ { "name": "user", "description": "managing arcstorage system users" } ], "paths": { "/api/storage/{objId}/renew": { "put": { "tags": [ "object-write-api" ], "summary": "Renews logically removed object by setting its state to ARCHIVED.", "description": "Not allowed for AIP XML objects.", "operationId": "renew", "parameters": [ { "name": "objId", "in": "path", "description": "object id", "required": true, "schema": { "type": "string" } } ], "responses": { "403": { "description": "operation forbidden with respect to the current object state" }, "500": { "description": "no logical storage attached, or other internal server error" }, "200": { "description": "object successfully renewed" }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "some attached logical storage is currently not reachable or system is in readonly state" } } } }, "/api/storage/{objId}/remove": { "put": { "tags": [ "object-write-api" ], "summary": "Logically removes object by setting its state to REMOVED.", "description": "Not allowed for AIP XML objects.", "operationId": "remove", "parameters": [ { "name": "objId", "in": "path", "description": "object id", "required": true, "schema": { "type": "string" } } ], "responses": { "403": { "description": "operation forbidden with respect to the current object state" }, "500": { "description": "no logical storage attached, or other internal server error" }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "200": { "description": "object successfully removed" }, "503": { "description": "some attached logical storage is currently not reachable or system is in readonly state" } } } }, "/api/user/register": { "post": { "tags": [ "user" ], "summary": "Register user.", "description": "DataSpace should be simple string, no dashes, slashes, uppercase letters, spaces or underscores. If the user has READ/READ-WRITE role and the dataSpace is new, the dataSpace should be activated by another endpoint.", "operationId": "registerUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "required": true }, "responses": { "400": { "description": "Wrong JSON | username/password/role missing | role!=ADMIN and dataSpace missing | role==ADMIN and dataSpace not null", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/User" } } } }, "409": { "description": "username already exists", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/User" } } } } } } }, "/api/user/activate/{dataSpace}": { "post": { "tags": [ "user" ], "summary": "Activates dataSpace i.e. creates folders/buckets etc. at all logical storages.", "description": "DataSpace should be simple string, no dashes, slashes, uppercase letters, spaces or underscores.", "operationId": "activateDataSpace", "parameters": [ { "name": "dataSpace", "in": "path", "description": "dataSpace", "required": true, "schema": { "type": "string" } } ], "responses": { "500": { "description": "no logical storage attached or internal server error" }, "503": { "description": "some logical storage not reachable or system is in readonly state" } } } }, "/api/storage/{aipId}/update": { "post": { "tags": [ "object-write-api" ], "summary": "Versioning of the AIP XML: stores new AIP XML into Archival Storage.", "description": "Sync flag is set to false for batch AIP XML updates from Ingest. Sync flag is set to true for AIP XML updates invoked from user's interaction with the AIP XML editor in GUI.", "operationId": "saveXml", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP id", "required": true, "schema": { "type": "string" } }, { "name": "checksumValue", "in": "query", "description": "AIP XML checksum value", "required": true, "schema": { "type": "string" } }, { "name": "checksumType", "in": "query", "description": "AIP XML checksum type", "required": true, "schema": { "type": "string", "enum": [ "MD5", "SHA512" ] } }, { "name": "sync", "in": "query", "description": "synchronous/asynchronous processing flag", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "v", "in": "query", "description": "version number of the AIP XML, is automatically set to the lastVersion+1 if not specified", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "xml" ], "type": "object", "properties": { "xml": { "type": "string", "format": "binary" } } } } } }, "responses": { "500": { "description": "no logical storage attached, or other internal server error" }, "200": { "description": "AIP XML successfully stored" }, "422": { "description": "the checksum computed after the transfer does not match the provided checksum" }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "409": { "description": "bad XML version number provided (not following the sequence)" }, "403": { "description": "operation forbidden with respect to the current AIP state" }, "503": { "description": "some attached logical storage is currently not reachable or system is in readonly state" } } } }, "/api/storage/{aipId}/files-specified": { "post": { "tags": [ "object-read-api" ], "summary": "Return specified files of AIP packed in ZIP", "description": "DOES NOT validate the AIP.. does not return any AIP XML, requires some local storage to be reachable", "operationId": "getAipFilesReducedByListOfPaths", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "uniqueItems": true, "type": "array", "description": "Set of wanted files paths sent as RequestBody", "items": { "type": "string" } } } }, "required": true }, "responses": { "200": { "description": "AIP successfully returned", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "all attached logical storages are currently unreachable" }, "500": { "description": "file is corrupted at all storages, no logical storage attached, or other internal server error" }, "403": { "description": "operation forbidden with respect to the current AIP state" } } } }, "/api/storage/{aipId}/files-reduced": { "post": { "tags": [ "object-read-api" ], "summary": "Return specified files of AIP packed in ZIP", "description": "DOES NOT validate the AIP, does not return any AIP XML, requires some local storage to be reachable", "operationId": "getAipFilesReducedByRegex", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataReduction" } } }, "required": true }, "responses": { "200": { "description": "AIP successfully returned", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "all attached logical storages are currently unreachable" }, "500": { "description": "file is corrupted at all storages, no logical storage attached, or other internal server error" }, "403": { "description": "operation forbidden with respect to the current AIP state" } } } }, "/api/storage/{aipId}/aip-with-files-specified": { "post": { "tags": [ "object-read-api" ], "summary": "Return AIP with specified files packed in ZIP", "description": "validates the AIP and if it is invalidtries to recover it from other storage.. does not return only files but also AIP XML(s)", "operationId": "getAipReducedByListOfFiles", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP ID", "required": true, "schema": { "type": "string" } }, { "name": "all", "in": "query", "description": "true to return all XMLs, otherwise only the latest is returned", "required": false, "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "uniqueItems": true, "type": "array", "description": "Set of wanted files paths sent as RequestBody", "items": { "type": "string" } } } }, "required": true }, "responses": { "200": { "description": "AIP successfully returned", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "all attached logical storages are currently unreachable" }, "500": { "description": "file is corrupted at all storages, no logical storage attached, or other internal server error" }, "403": { "description": "operation forbidden with respect to the current AIP state" } } } }, "/api/storage/{aipId}/aip-with-files-reduced": { "post": { "tags": [ "object-read-api" ], "summary": "Return AIP with specified files packed in ZIP", "description": "validates the AIP and if it is invalidtries to recover it from other storage.. does not return only files but also AIP XML(s)", "operationId": "getAipReducedByRegex", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP ID", "required": true, "schema": { "type": "string" } }, { "name": "all", "in": "query", "description": "true to return all XMLs, otherwise only the latest is returned", "required": false, "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataReduction" } } }, "required": true }, "responses": { "200": { "description": "AIP successfully returned", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "all attached logical storages are currently unreachable" }, "500": { "description": "file is corrupted at all storages, no logical storage attached, or other internal server error" }, "403": { "description": "operation forbidden with respect to the current AIP state" } } } }, "/api/storage/save": { "post": { "tags": [ "object-write-api" ], "summary": "Stores AIP parts (SIP and AIP XML) into Archival Storage and returns the AIP ID.", "operationId": "saveAip", "parameters": [ { "name": "sipChecksumValue", "in": "query", "description": "value of the SIP checksum", "required": true, "schema": { "type": "string" } }, { "name": "sipChecksumType", "in": "query", "description": "type of the SIP checksum", "required": true, "schema": { "type": "string", "enum": [ "MD5", "SHA512" ] } }, { "name": "aipXmlChecksumValue", "in": "query", "description": "value of the AIP XML checksum", "required": true, "schema": { "type": "string" } }, { "name": "aipXmlChecksumType", "in": "query", "description": "type of the AIP XML checksum", "required": true, "schema": { "type": "string", "enum": [ "MD5", "SHA512" ] } }, { "name": "UUID", "in": "query", "description": "UUID of the AIP, generated if not specifies", "required": false, "schema": { "type": "string", "default": "" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "aipXml", "sip" ], "type": "object", "properties": { "sip": { "type": "string", "description": "SIP file", "format": "binary" }, "aipXml": { "type": "string", "description": "AIP XML file", "format": "binary" } } } } } }, "responses": { "500": { "description": "no logical storage attached, or other internal server error", "content": { "*/*": { "schema": { "type": "string" } } } }, "422": { "description": "the checksum computed after the transfer does not match the provided checksum", "content": { "*/*": { "schema": { "type": "string" } } } }, "200": { "description": "AIP successfully stored", "content": { "*/*": { "schema": { "type": "string" } } } }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID", "content": { "*/*": { "schema": { "type": "string" } } } }, "503": { "description": "some attached logical storage is currently not reachable or system is in readonly state", "content": { "*/*": { "schema": { "type": "string" } } } } } } }, "/api/storage/object/info": { "post": { "tags": [ "object-info-api" ], "summary": "Retrieves metadata of objects.", "description": "Sorted by creation date ASC. For non-admin users, only records belonging to the user's dataspace are retrieved.", "operationId": "getObjectsMeta", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimestampOffsetLimitDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectInfoDto" } } } } } } } }, "/api/storage/audit": { "post": { "tags": [ "object-info-api" ], "summary": "Retrieves audit of objects.", "description": "Sorted by creation date ASC. For non-admin users, only records belonging to the user's dataspace are retrieved.", "operationId": "getAudit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimestampOffsetLimitDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectAuditDto" } } } } } } } }, "/api/administration/storage": { "get": { "tags": [ "storage-administration-api" ], "summary": "Returns all attached logical storages.", "operationId": "getAll", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Storage" } } } } } } }, "post": { "tags": [ "storage-administration-api" ], "summary": "Attaches new logical storage and starts synchronization.", "description": "After the initial checks are done, process continues asynchronously. See documentation for example JSON configurations", "operationId": "attachNewStorage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Storage" } } }, "required": true }, "responses": { "503": { "description": "storage to be synchronized is not reachable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Storage" } } } }, "567": { "description": "cant create some dataspace at the storage", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Storage" } } } }, "566": { "description": "synchronization initialization timeout because there are still processing objects at the archival storage", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Storage" } } } }, "409": { "description": "storage already exists", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Storage" } } } }, "400": { "description": "invalid configuration", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Storage" } } } } } } }, "/api/administration/storage/{id}/detach": { "post": { "tags": [ "storage-administration-api" ], "summary": "Detaches a logical storage.", "operationId": "detach", "parameters": [ { "name": "id", "in": "path", "description": "id of the logical storage", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/administration/storage/{id}/attach": { "post": { "tags": [ "storage-administration-api" ], "summary": "Attaches existing detached logical storage.", "operationId": "attach", "parameters": [ { "name": "id", "in": "path", "description": "id of the logical storage", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/administration/storage/update": { "post": { "tags": [ "storage-administration-api" ], "summary": "Updates a logical storage.", "description": "Only name, priority and note flags are updatable, others are ignored.", "operationId": "update", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageUpdateDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Storage" } } } } } } }, "/api/administration/storage/check_reachability": { "post": { "tags": [ "storage-administration-api" ], "summary": "Check reachability of all storages", "operationId": "checkReachability", "responses": { "200": { "description": "OK" } } } }, "/api/administration/recover_db": { "post": { "tags": [ "system-administration-api" ], "summary": "Recovers database from the storage.", "description": " Synchronous call. System has to be set to read-only mode. Currently the recovery is implemented only for local FS/ZFS. If the object metadata is present in DB and also at storage, the metadata are compared and if not equal, system logs (warn) the conflict and if override parameter is set to true, DB metadata are overridden by storage metadata. System also logs (error) all objects which are in DB but not at storage. ", "operationId": "recoverDbFromStorage", "parameters": [ { "name": "storageId", "in": "query", "description": "storage id", "required": true, "schema": { "type": "string" } }, { "name": "override", "in": "query", "description": "whether to override conflicting metadata in DB with those from storage", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "503": { "description": "logical storage unreachable" }, "403": { "description": "Not authorized or system is in read-write mode" } } } }, "/api/administration/config": { "get": { "tags": [ "system-administration-api" ], "summary": "Returns configuration", "operationId": "get", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SystemState" } } } } } }, "post": { "tags": [ "system-administration-api" ], "summary": "Updates system properties", "operationId": "update_1", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemStateUpdateDto" } } }, "required": true }, "responses": { "400": { "description": "the config breaks the basic LTP policy (e.g. count of storages)", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SystemState" } } } } } } }, "/api/administration/config/storage/{id}/primary": { "post": { "tags": [ "system-administration-api" ], "summary": "Switches primary storage.", "description": "In order to succeed, all storage queues must be empty.", "operationId": "switchPrimaryStorage", "parameters": [ { "name": "id", "in": "path", "description": "ID of new primary storage", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/administration/config/read_write": { "post": { "tags": [ "system-administration-api" ], "summary": "Sets system to read-write mode", "operationId": "setReadWrite", "responses": { "200": { "description": "OK" } } } }, "/api/administration/config/read_only": { "post": { "tags": [ "system-administration-api" ], "summary": "Sets system to read-only mode", "operationId": "setReadOnly", "responses": { "200": { "description": "OK" } } } }, "/api/administration/cleanup": { "post": { "tags": [ "system-administration-api" ], "summary": "Cleans storage. In order to succeed, all storages must be reachable.", "description": "By default only failed package are cleaned (i.e. rolled back/deleted from all storages). If 'all' is set to true, also currently processing/stucked packages and tmp folder is cleaned.", "operationId": "cleanup", "parameters": [ { "name": "all", "in": "query", "description": "all", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "503": { "description": "some logical storage unreachable" } } } }, "/api/administration/cleanup/object/{objId}": { "post": { "tags": [ "system-administration-api" ], "summary": "Cleans one particular object. In order to succeed, all storages must be reachable.", "description": "Object must be in failed or processing state. If the object is in processing state, caller must ensure that the object is not actually processing but the state was left processing becausesome unexpected error has occurred (e.g. system crashed).", "operationId": "cleanupOne", "parameters": [ { "name": "objId", "in": "path", "description": "database id of the object", "required": true, "schema": { "type": "string" } } ], "responses": { "503": { "description": "some logical storage unreachable" } } } }, "/api/storage/{aipId}": { "get": { "tags": [ "object-read-api" ], "summary": "Return specified AIP as a ZIP package", "operationId": "getAip", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP ID", "required": true, "schema": { "type": "string" } }, { "name": "all", "in": "query", "description": "true to return all XMLs, otherwise only the latest is returned", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "AIP successfully returned", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "all attached logical storages are currently unreachable" }, "500": { "description": "file is corrupted at all storages, no logical storage attached, or other internal server error" }, "403": { "description": "operation forbidden with respect to the current AIP state" } } } }, "/api/storage/{aipId}/xml": { "get": { "tags": [ "object-read-api" ], "summary": "Return specified AIP XML", "operationId": "getXml", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP ID", "required": true, "schema": { "type": "string" } }, { "name": "v", "in": "query", "description": "version number of XML, if not set the latest version is returned", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "AIP XML successfully returned", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "all attached logical storages are currently unreachable" }, "500": { "description": "file is corrupted at all storages, no logical storage attached, or other internal server error" }, "403": { "description": "operation forbidden with respect to the current AIP state" } } } }, "/api/storage/{aipId}/xml/{xmlVersion}/state": { "get": { "tags": [ "object-info-api" ], "summary": "State of XML.", "description": "Retrieves the state of XML stored in database.", "operationId": "getXmlState", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP ID", "required": true, "schema": { "type": "string" } }, { "name": "xmlVersion", "in": "path", "description": "XML version", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "404": { "description": "XML not found", "content": { "*/*": { "schema": { "type": "string", "enum": [ "PRE_PROCESSING", "PROCESSING", "ARCHIVED", "ROLLED_BACK", "DELETED", "REMOVED", "ARCHIVAL_FAILURE", "DELETION_FAILURE", "ROLLBACK_FAILURE", "FORGOT" ] } } } }, "200": { "description": "state of XML successfully retrieved", "content": { "*/*": { "schema": { "type": "string", "enum": [ "PRE_PROCESSING", "PROCESSING", "ARCHIVED", "ROLLED_BACK", "DELETED", "REMOVED", "ARCHIVAL_FAILURE", "DELETION_FAILURE", "ROLLBACK_FAILURE", "FORGOT" ] } } } } } } }, "/api/storage/{aipId}/state": { "get": { "tags": [ "object-info-api" ], "summary": "State of AIP.", "description": "Retrieves the state of AIP stored in database.", "operationId": "getAipState", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP id", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "AIP with the id not found", "content": { "*/*": { "schema": { "type": "string", "enum": [ "PRE_PROCESSING", "PROCESSING", "ARCHIVED", "ROLLED_BACK", "DELETED", "REMOVED", "ARCHIVAL_FAILURE", "DELETION_FAILURE", "ROLLBACK_FAILURE", "FORGOT" ] } } } }, "200": { "description": "state of AIP successfully retrieved", "content": { "*/*": { "schema": { "type": "string", "enum": [ "PRE_PROCESSING", "PROCESSING", "ARCHIVED", "ROLLED_BACK", "DELETED", "REMOVED", "ARCHIVAL_FAILURE", "DELETION_FAILURE", "ROLLBACK_FAILURE", "FORGOT" ] } } } } } } }, "/api/storage/{aipId}/info": { "get": { "tags": [ "object-info-api" ], "summary": "Verifies AIP consistency at given storage and retrieves result.", "description": "If the AIP is not in some final, consistent state even in DB the storage is not checked and only DB data are returned.", "operationId": "getAipInfo", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP id", "required": true, "schema": { "type": "string" } }, { "name": "storageId", "in": "query", "description": "id of the logical storage", "required": true, "schema": { "type": "string" } } ], "responses": { "403": { "description": "not authorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AipConsistencyVerificationResultDto" } } } }, "200": { "description": "AIP successfully deleted", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AipConsistencyVerificationResultDto" } } } }, "503": { "description": "storage is not reachable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AipConsistencyVerificationResultDto" } } } }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AipConsistencyVerificationResultDto" } } } }, "500": { "description": "internal server error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AipConsistencyVerificationResultDto" } } } } } } }, "/api/storage/{aipId}/data": { "get": { "tags": [ "object-read-api" ], "summary": "Return data (zip part) of specified AIP without rezipping the data thus keeping original checksum", "operationId": "getAipDataAsIs", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP ID", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "all attached logical storages are currently unreachable" }, "200": { "description": "AIP data successfully returned", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "description": "file is corrupted at all storages, no logical storage attached, or other internal server error" }, "403": { "description": "operation forbidden with respect to the current AIP state" } } } }, "/api/storage/object/{id}": { "get": { "tags": [ "object-read-api" ], "summary": "Retrieves content of object.", "description": "Supported only for AIP data and AIP XML objects. For non-admin users, the content is retrieved only if the object belongs to the users's dataspace.", "operationId": "getObject", "parameters": [ { "name": "id", "in": "path", "description": "DB ID", "required": true, "schema": { "type": "string" } } ], "responses": { "403": { "description": "operation forbidden with respect to the current object state" }, "200": { "description": "content successfully returned", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "all attached logical storages are currently unreachable" }, "500": { "description": "file is corrupted at all storages, no logical storage attached, or other internal server error" } } } }, "/api/storage/object/{id}/info": { "get": { "tags": [ "object-info-api" ], "summary": "Retrieves metadata of object.", "description": "For non-admin users, the metadata are retrieved only if the object belongs to the users's dataspace.", "operationId": "getObjectMeta", "parameters": [ { "name": "id", "in": "path", "description": "DB ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ObjectInfoDto" } } } } } } }, "/api/administration/storage/{id}": { "get": { "tags": [ "storage-administration-api" ], "summary": "Returns logical storage with specified ID.", "operationId": "getOne", "parameters": [ { "name": "id", "in": "path", "description": "id of the logical storage", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Storage" } } } } } }, "delete": { "tags": [ "storage-administration-api" ], "summary": "Removes a logical storage.", "operationId": "delete_1", "parameters": [ { "name": "id", "in": "path", "description": "id of the logical storage", "required": true, "schema": { "type": "string" } } ], "responses": { "403": { "description": "not authorized or can't be deleted because count of logical storage would be less than the configured minimum" } } } }, "/api/administration/storage/{id}/state": { "get": { "tags": [ "storage-administration-api" ], "summary": "Returns state of logical storage.", "description": "Data returned depends on the logical storage. E.g. self-healing data are returned only if self-healing is supported by the storage.", "operationId": "getStorageState", "parameters": [ { "name": "id", "in": "path", "description": "id of the logical storage", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/StorageStateDto" } } } } } } }, "/api/administration/storage/sync/{id}": { "get": { "tags": [ "storage-administration-api" ], "summary": "Retrieves sync status entity for the storage.", "operationId": "getSyncStatusOfStorage", "parameters": [ { "name": "id", "in": "path", "description": "id of the storage", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "no sync status for this storage", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/StorageSyncStatus" } } } } } } }, "/api/administration/storage/basic": { "get": { "tags": [ "storage-administration-api" ], "summary": "Returns simple DTOs of all attached logical storages.", "operationId": "getAllAsDtos", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorageBasicDto" } } } } } } } }, "/api/administration/backup": { "get": { "tags": [ "system-administration-api" ], "summary": "Exports all objects which have changed in the specified time range.", "description": "Once the reachability of export location is verified, the response is returned and process continues asynchronously. If since/until is not filled, MIN/MAX is used.", "operationId": "backup", "parameters": [ { "name": "since", "in": "query", "description": "since", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "until", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "500": { "description": "Export location unreachable or other internal error." } } } }, "/api/storage/{objId}": { "delete": { "tags": [ "object-write-api" ], "summary": "Physically deletes object and sets its state to DELETED.", "description": "Not allowed for AIP XML objects.", "operationId": "delete", "parameters": [ { "name": "objId", "in": "path", "description": "object id", "required": true, "schema": { "type": "string" } } ], "responses": { "403": { "description": "operation forbidden with respect to the current object state" }, "500": { "description": "no logical storage attached, or other internal server error" }, "200": { "description": "object successfully deleted" }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "some attached logical storage is currently not reachable or system is in readonly state" } } } }, "/api/storage/{objId}/rollback": { "delete": { "tags": [ "object-write-api" ], "summary": "Deletes the object data.", "description": "If the object is AIP, it has to contain exactly one AIP XML which is also rolled back. Metadata and DB records remains persistent with state set to ROLLED_BACK. If the object to rollback does not exists, then do nothing.", "operationId": "rollback", "parameters": [ { "name": "objId", "in": "path", "description": "object id", "required": true, "schema": { "type": "string" } } ], "responses": { "500": { "description": "no logical storage attached, or other internal server error" }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "200": { "description": "object successfully rolled back or rollback skipped because the object was not found" }, "403": { "description": "trying to rollback AIP XML (there is a special endpoint for that case) OR trying to rollback AIP which has more than one AIP XML linked" }, "503": { "description": "some attached logical storage is currently not reachable or system is in readonly state" } } } }, "/api/storage/{objId}/forget": { "delete": { "tags": [ "object-write-api" ], "summary": "Forgets the object.", "description": "If the object is AIP, it has to contain exactly one AIP XML which is also forget. All Metadata and DB records are deleted together with file content.If the object to forget does not exists, then do nothing.", "operationId": "forget", "parameters": [ { "name": "objId", "in": "path", "description": "object id", "required": true, "schema": { "type": "string" } } ], "responses": { "500": { "description": "no logical storage attached, or other internal server error" }, "403": { "description": "forget feature not allowed or trying to forget AIP XML (there is a special endpoint for that case) OR trying to forget AIP which has more than one AIP XML linked" }, "200": { "description": "object successfully forgotten or forget call skipped because the object was not found" }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "some attached logical storage is currently not reachable or system is in readonly state" } } } }, "/api/storage/{aipId}/rollbackXml/{xmlVersion}": { "delete": { "tags": [ "object-write-api" ], "summary": "Deletes data of the latest AIP XML. Version set in the path variable must be the latest AIP XML of the AIP.", "description": "If the AIP or XML does not exists, Archival storage silently skips the request- ", "operationId": "rollbackXml", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP id", "required": true, "schema": { "type": "string" } }, { "name": "xmlVersion", "in": "path", "description": "XML version", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "500": { "description": "no logical storage attached, or other internal server error" }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "200": { "description": "object successfully rolled back or rollback skipped because the object was not found" }, "403": { "description": "if the XML is version 1 (whole AIP should be rolled back instead) or if this is not the latest XML version of the AIP (newer versions exist)" }, "503": { "description": "some attached logical storage is currently not reachable or system is in readonly state" } } } }, "/api/storage/{aipId}/forgetXml/{xmlVersion}": { "delete": { "tags": [ "object-write-api" ], "summary": "Deletes the latest AIP XML. Version set in the path variable must be the latest AIP XML of the AIP.", "description": "If the AIP or XML does not exists, Archival storage silently skips the request- ", "operationId": "forgetXml", "parameters": [ { "name": "aipId", "in": "path", "description": "AIP id", "required": true, "schema": { "type": "string" } }, { "name": "xmlVersion", "in": "path", "description": "XML version", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "403": { "description": "forget feature not allowed or the XML is version 1 (whole AIP should be forgotten instead) or if this is not the latest XML version of the AIP (newer versions exist)" }, "500": { "description": "no logical storage attached, or other internal server error" }, "200": { "description": "object successfully forgotten or forget call skipped because the object was not found" }, "400": { "description": "bad request, e.g. the specified id is not a valid UUID" }, "503": { "description": "some attached logical storage is currently not reachable or system is in readonly state" } } } } }, "components": { "schemas": { "User": { "required": [ "role", "username" ], "type": "object", "properties": { "id": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "updated": { "type": "string", "format": "date-time" }, "deleted": { "type": "string", "format": "date-time" }, "username": { "type": "string" }, "password": { "type": "string", "writeOnly": true }, "email": { "type": "string" }, "dataSpace": { "type": "string" }, "role": { "type": "string", "enum": [ "ROLE_ADMIN", "ROLE_READ", "ROLE_READ_WRITE" ] } }, "description": "User to be registered" }, "DataReduction": { "required": [ "mode", "regexes" ], "type": "object", "properties": { "regexes": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "INCLUDE", "EXCLUDE" ] } }, "description": "Set of wanted files paths sent as RequestBody" }, "TimestampOffsetLimitDto": { "type": "object", "properties": { "from": { "type": "string", "description": "exclusive offset, if set, only objects with created > from are retrieved", "format": "date-time" }, "count": { "type": "integer", "description": "limit of retrieved records", "format": "int32" } }, "description": "specification of the record set" }, "Checksum": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "MD5", "SHA512" ] }, "value": { "type": "string" } } }, "ObjectInfoDto": { "type": "object", "properties": { "id": { "type": "string" }, "idInStorage": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "checksum": { "$ref": "#/components/schemas/Checksum" }, "dataSpace": { "type": "string" }, "state": { "type": "string", "enum": [ "PRE_PROCESSING", "PROCESSING", "ARCHIVED", "ROLLED_BACK", "DELETED", "REMOVED", "ARCHIVAL_FAILURE", "DELETION_FAILURE", "ROLLBACK_FAILURE", "FORGOT" ] }, "type": { "type": "string", "enum": [ "SIP", "XML", "OBJECT" ] } } }, "ObjectAuditDto": { "type": "object", "properties": { "id": { "type": "string" }, "idInDatabase": { "type": "string" }, "idInStorage": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "dataSpace": { "type": "string" }, "operation": { "type": "string", "enum": [ "REMOVAL", "DELETION", "RENEWAL", "ROLLBACK", "ARCHIVAL_RETRY", "FORGET", "ARCHIVED" ] } } }, "Storage": { "required": [ "config", "host", "name", "storageType" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer", "format": "int32" }, "priority": { "type": "integer", "format": "int32" }, "storageType": { "type": "string", "enum": [ "FS", "ZFS", "CEPH" ] }, "note": { "type": "string" }, "config": { "type": "string" }, "reachable": { "type": "boolean" }, "detachedByAdmin": { "type": "string", "format": "date-time" }, "detachedByError": { "type": "string", "format": "date-time" }, "detached": { "type": "boolean" } }, "description": "logical storage entity" }, "StorageUpdateDto": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string" }, "priority": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "note": { "type": "string" } }, "description": "update DTO of the logical storage entity" }, "SystemStateUpdateDto": { "required": [ "minStorageCount", "reachabilityCheckIntervalInMinutes" ], "type": "object", "properties": { "minStorageCount": { "type": "integer", "format": "int32" }, "reachabilityCheckIntervalInMinutes": { "type": "integer", "format": "int32" } }, "description": "dto" }, "SystemState": { "type": "object", "properties": { "id": { "type": "string" }, "minStorageCount": { "type": "integer", "format": "int32" }, "readOnly": { "type": "boolean" }, "reachabilityCheckIntervalInMinutes": { "type": "integer", "format": "int32" }, "lastReachabilityCheck": { "type": "string", "format": "date-time" }, "lastVerifiedObjectCreation": { "type": "string", "format": "date-time" }, "primaryStorage": { "$ref": "#/components/schemas/Storage" } } }, "AipConsistencyVerificationResultDto": { "type": "object", "properties": { "storageName": { "type": "string" }, "storageType": { "type": "string", "enum": [ "FS", "ZFS", "CEPH" ] }, "reachable": { "type": "boolean" }, "aipState": { "$ref": "#/components/schemas/ObjectConsistencyVerificationResultDto" }, "xmlStates": { "type": "array", "items": { "$ref": "#/components/schemas/XmlConsistencyVerificationResultDto" } } } }, "ObjectConsistencyVerificationResultDto": { "type": "object", "properties": { "databaseId": { "type": "string" }, "storageId": { "type": "string" }, "state": { "type": "string", "enum": [ "PRE_PROCESSING", "PROCESSING", "ARCHIVED", "ROLLED_BACK", "DELETED", "REMOVED", "ARCHIVAL_FAILURE", "DELETION_FAILURE", "ROLLBACK_FAILURE", "FORGOT" ] }, "contentConsistent": { "type": "boolean" }, "metadataConsistent": { "type": "boolean" }, "storageChecksum": { "$ref": "#/components/schemas/Checksum" }, "databaseChecksum": { "$ref": "#/components/schemas/Checksum" }, "created": { "type": "string", "format": "date-time" } } }, "XmlConsistencyVerificationResultDto": { "type": "object", "properties": { "databaseId": { "type": "string" }, "storageId": { "type": "string" }, "state": { "type": "string", "enum": [ "PRE_PROCESSING", "PROCESSING", "ARCHIVED", "ROLLED_BACK", "DELETED", "REMOVED", "ARCHIVAL_FAILURE", "DELETION_FAILURE", "ROLLBACK_FAILURE", "FORGOT" ] }, "contentConsistent": { "type": "boolean" }, "metadataConsistent": { "type": "boolean" }, "storageChecksum": { "$ref": "#/components/schemas/Checksum" }, "databaseChecksum": { "$ref": "#/components/schemas/Checksum" }, "created": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int32" } } }, "StorageStateDto": { "type": "object", "properties": { "storage": { "$ref": "#/components/schemas/Storage" }, "storageStateData": { "type": "object", "additionalProperties": { "type": "object" } } } }, "StorageSyncStatus": { "type": "object", "properties": { "id": { "type": "string" }, "storage": { "$ref": "#/components/schemas/Storage" }, "created": { "type": "string", "format": "date-time" }, "updated": { "type": "string", "format": "date-time" }, "total": { "type": "integer", "format": "int64" }, "done": { "type": "integer", "format": "int64" }, "exceptionMsg": { "type": "string" }, "exceptionStackTrace": { "type": "string" }, "exceptionInfo": { "type": "object", "properties": { "stackTrace": { "type": "array", "items": { "type": "object", "properties": { "classLoaderName": { "type": "string" }, "moduleName": { "type": "string" }, "moduleVersion": { "type": "string" }, "methodName": { "type": "string" }, "fileName": { "type": "string" }, "lineNumber": { "type": "integer", "format": "int32" }, "nativeMethod": { "type": "boolean" }, "className": { "type": "string" } } } }, "message": { "type": "string" }, "localizedMessage": { "type": "string" } }, "writeOnly": true }, "finished": { "type": "boolean" } } }, "StorageBasicDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "storageType": { "type": "string" } } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } } }