Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Onezone REST API Oneprovider REST API Onepanel REST API

Get archive information

GET /archives/{aid}

Returns the basic information about an archive.

This operation requires space_view_archives privilege.

Example cURL requests

Get the basic information about archive

curl -H "X-Auth-Token: $TOKEN" -X GET "https://$PROVIDER_HOST/api/v3/oneprovider/archives/$ARCHIVE_ID"

{
    "archiveId": "ae6f78c89a97c9e78e891105f703bcb8",
    "state": "preserved",
    "datasetId": "1f4b762b1380946e73aeca574c77f14c",
    "rootDirectoryId": "00000000006CB663736861726547756964233339643236366165646365",
    "creationTime": 1576152793,
    "config": {
      "incremental": {"enabled": true},
      "includeDip": false,
      "layout": "bagit",
    },
    "preservedCallback": "https://example.org/preserved_archives",
    "deletedCallback": null,
    "description": "Archived dataset with experiment data from 2021.",
    "stats": {
        "filesArchived": 7940,
        "filesFailed": 3,
        "bytesArchived": 879245378924537
    },
    "baseArchiveId": "ae6f78c89a97c9e78e891105f703bcb8",
    "relatedAipId": "e891105f703bcb8ae6f78c89a97c9e78",
    "relatedDipId": "78e891105f703bcb8ae6f78c89a97c9e"
}

Path parameters

Parameter Type & Description
aid required
string

Archive Id

Request Examples

Shell
oneprovider-rest-cli getArchive aid=$ARCHIVE_ID

Responses

application/json
200

The archive information.

Property
Type & Description
archiveId
string

Archive Id.

state
string (ArchiveState)

The state of the archive:

  • pending - the archive creation has been scheduled, but the process of archiving data on the storage has not started yet,

  • building - the process of archiving data on the storage is in progress,

  • verifying - the process of verifying archived data on the storage is in progress,

  • preserved - all data has been successfully archived on the storage,

  • verification_failed - the data in the archive was modified externally during the archiving process and the archive is considered inconsistent,

  • failed - an error occured during the process of archiving data on the storage,

  • purging - the archive is being deleted. In the process, the archived data is deleted from the storage, then all the information concerning the archive is deleted.

Enum:
pending building preserved failed purging
datasetId
string

Id of the dataset from which the archive has been created.

rootDirectoryId
string

Id of the hidden directory in the space where the archive is stored.

creationTime
integer (Timestamp)

Timestamp in seconds (UNIX epoch), e.g. 1563819329.

config
object (ArchiveConfig)

Parameters used to configure the process of creating an archive.
incremental
object (ArchiveIncremental)

This field determines whether archive is incremental - storing only files that have changed in comparison to the base archive (provided under the "basedOn" key). Unchanged files are preserved as hard links to the corresponding files in the base archive. If does not enabled, all files belonging to the dataset are stored directly in the archive.
enabled required
boolean
basedOn
string (ArchiveBase)

This attribute determines which archive will be the base archive for incremental creation of a new archive (consult description of the incremental parameter). If not set, last successfully preserved archive will be used. If incremental is not enabled this field is ignored.

includeDip
boolean (ArchiveIncludeDip)

This flag determines whether dissemination information package (DIP) is created alongside with archival information package (AIP), on the storage. For more information on DIP and AIP please consult Open Archival Information System.

layout
string (ArchiveLayout)

The layout of files and directories in an archive.

  • plain - Structure of the data in the archive is an exact copy of the dataset.

  • bagit - Data in the archive are stored in the bagit format.

Enum:
plain bagit
createNestedArchives
boolean (ArchiveCreateNestedArchives)

This flag determines the strategy of archiving nested datasets (i. e. datasets inside the dataset that is being archived).

If set to true, a separate archive will be created for each nested dataset, and a symbolic link to the nested archive will be created in the parent archive in the place of the nested dataset's root file/directory. The procedure is recursive and may effectively create a tree of linked archives.

If set to false, the resulting archive will be monolithic, i. e. all files and directories from nested datasets will be copied directly to the archive, in their respective locations. Effectively, the internal hierarchy of datasets has no impact on the resulting archive content.

followSymlinks
boolean (ArchiveFollowSymlinks)

This flag determines whether symbolic links pointing to paths outside of the dataset should be resolved during archive creation.

If set to true, valid links will be resolved and their target files/directories will be copied to the archive in their place. Invalid symbolic links (not resolvable to a valid path in the space) will be ignored and not included in the archive.

If set to false, symbolic links will be copied to the resulting archive and their target paths will not be modified. Note that these symbolic links may target modifiable files in the space.

NOTE: Symbolic links pointing to files inside the dataset are always preserved, regardless of this setting. Their target paths are reconstructed to point to the corresponding files in the resulting archive.

description
string (ArchiveDescription)

User defined description of the archive.

preservedCallback
string (ArchivePreservedCallback)

URL on which POST request will be performed to notify that process of persisting an archive has finished. The callback request will include body in the following JSON format:

{
    "archiveId": "$ARCHIVE_ID",
    "datasetId" : "$DATASET_ID",
    "error": "Error description"
}

"error" field will have null value if archivisation has been finished successfully.

Requested server should response with one of 2xx HTTP codes. If the request fails or returns any other HTTP code, it will be retried.

deletedCallback
string (ArchiveDeletedCallback)

URL on which POST request will be performed to notify that process of purging an archive has finished. The callback request will include body in the following JSON format:

{
    "archiveId": "$ARCHIVE_ID",
    "datasetId": "$DATASET_ID",
    "error": "Error description"
}

"error" field will have null value if purging of an archive has been finished successfully.

Requested server should response with one of 2xx HTTP codes. If the request fails or returns any other HTTP code, it will be retried.

stats
object (ArchiveStats)

Archivisation job statistics.
filesArchived required
integer

Counter of successfully archived files.

filesFailed required
integer

Counter of files for which archiving process has failed.

bytesArchived required
integer

Total size of already archived files in bytes.

baseArchiveId
string (ArchiveBase)

This attribute determines which archive will be the base archive for incremental creation of a new archive (consult description of the incremental parameter). If not set, last successfully preserved archive will be used. If incremental is not enabled this field is ignored.

relatedAipId
string

Id of the related archival information package (AIP) archive. Can be null when there is no such archive.

relatedDipId
string

Id of the related dissemination information package (DIP) archive. Can be null when there is no such archive.

Example

application/json
{
  "archiveId": "ae6f78c89a97c9e78e891105f703bcb8",
  "state": "preserved",
  "datasetId": "1f4b762b1380946e73aeca574c77f14c",
  "rootDirectoryId": "00000000006CB663736861726547756964233339643236366165646365",
  "creationTime": 1576152793,
  "config": {
    "incremental": {
      "enabled": true
    },
    "includeDip": false,
    "layout": "plain"
  },
  "preservedCallback": "https://example.org/preserved_archives",
  "deletedCallback": "https://example.org/deleted_archives",
  "description": "Archived dataset with experiment data from 2021.",
  "stats": {
    "filesArchived": 7940,
    "filesFailed": 3,
    "bytesArchived": 879245378924537
  },
  "baseArchiveId": "ae6f78c89a97c9e78e891105f703bcb8",
  "relatedAipId": "e891105f703bcb8ae6f78c89a97c9e78",
  "relatedDipId": "78e891105f703bcb8ae6f78c89a97c9e"
}
400

Invalid request.

Property
Type & Description
error
object (ErrorJson)

Object describing an error.
id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

ctx required
object (ErrorJsonCtx)

Technical information about error.
timestamp required
integer

Timestamp in milliseconds.

serviceReleaseVersion required
string

Release version of a product, for example "25.1".

serviceId required
string

Identifier of a service instance — either Oneprovider Id or "onezone".

serviceDomain required
string

Domain of the service.

serviceBuildVersion required
string

Build version of the service.

service required
string

Short name of service.

Enum:
ozw opw ozp opp
onedataErrorsRevision required
string

Revision of onedata-errors repo, where the error is defined.

module required
string

Module where the error occurred.

line required
integer

Line number in the module where the error occurred.

Example

application/json
{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.1",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}
403

Forbidden request.

Property
Type & Description
error
object (ErrorJson)

Object describing an error.
id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

ctx required
object (ErrorJsonCtx)

Technical information about error.
timestamp required
integer

Timestamp in milliseconds.

serviceReleaseVersion required
string

Release version of a product, for example "25.1".

serviceId required
string

Identifier of a service instance — either Oneprovider Id or "onezone".

serviceDomain required
string

Domain of the service.

serviceBuildVersion required
string

Build version of the service.

service required
string

Short name of service.

Enum:
ozw opw ozp opp
onedataErrorsRevision required
string

Revision of onedata-errors repo, where the error is defined.

module required
string

Module where the error occurred.

line required
integer

Line number in the module where the error occurred.

Example

application/json
{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.1",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}
404

Archive not found.

Property
Type & Description
error
object (ErrorJson)

Object describing an error.
id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

ctx required
object (ErrorJsonCtx)

Technical information about error.
timestamp required
integer

Timestamp in milliseconds.

serviceReleaseVersion required
string

Release version of a product, for example "25.1".

serviceId required
string

Identifier of a service instance — either Oneprovider Id or "onezone".

serviceDomain required
string

Domain of the service.

serviceBuildVersion required
string

Build version of the service.

service required
string

Short name of service.

Enum:
ozw opw ozp opp
onedataErrorsRevision required
string

Revision of onedata-errors repo, where the error is defined.

module required
string

Module where the error occurred.

line required
integer

Line number in the module where the error occurred.

Example

application/json
{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.1",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}
500

Internal server error.

Property
Type & Description
error
object (ErrorJson)

Object describing an error.
id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

ctx required
object (ErrorJsonCtx)

Technical information about error.
timestamp required
integer

Timestamp in milliseconds.

serviceReleaseVersion required
string

Release version of a product, for example "25.1".

serviceId required
string

Identifier of a service instance — either Oneprovider Id or "onezone".

serviceDomain required
string

Domain of the service.

serviceBuildVersion required
string

Build version of the service.

service required
string

Short name of service.

Enum:
ozw opw ozp opp
onedataErrorsRevision required
string

Revision of onedata-errors repo, where the error is defined.

module required
string

Module where the error occurred.

line required
integer

Line number in the module where the error occurred.

Example

application/json
{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.1",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}