Page History

Description

The bag Bag resource is used to store information about a deposit by a Depositor. When displaying a Bag to the outside world, the Ingest -Server and Replication Shell. It describes the base attributes of a collection in Chronopolis.

Bag

```
id: Long
```
```
name: String
```
```
depositor: String
```

location: String            // Relative location

tokenLocation: String       // Relative location

tagManifestDigest: String   // Ignored in json output

tokenDigest: String         // Ignored in json output

status: BagStatus           // enum; ignored in json output

fixityAlgorithm: String     // currently SHA-256

size: Long                  // size in bytes

totalFiles: Long            // Number of files in the bag, including the tag files

replicatingNodes: Set<Node> // Nodes who have successfully replicated the bag

requiredReplications: Int   // Number of replications required for preservation

JSON Example:

{ "id": 1, "name": "bag-0", "depositor": "test-depositor", "location": "bags/test-bag-0", "tokenLocation": "tokens/test-bag-0-tokens", "fixityAlgorithm": "SHA-256", "size": 14821 }

BagStatus

An enumerated type describing the various states a bag can have in its lifetime.

STAGED - The ingest-server has created a bag after being notified by an intake service that one was ready.
TOKENIZED - The ingest-server has created ACE tokens for a bag and written them to a file for replication
REPLICATING - Replication requests have been created for a bag which are currently in progress.
REPLICATED - All the replication requests for a bag have finished successfully and the number of required replications has been met.
ERROR - Somewhere along the line something bad happened.

Server brings in information about the Bag including its Replications and any active Staging Storage. The size and totalFiles are cached so that a summation does not need to be run every time a Bag is queried from the database.

Depositing Bags

Updating Bag Storage

API Description

Bag Model

Field	Type	Description
id	Long	The ID of the Bag
size	Long	The bag's size in bytes
name	String	The name of the Bag
creator	String	The user who created the bag in the Ingest Server
depositor	String	The organization to which the Bag belongs
status	BagStatus	Status of the Bag
totalFiles	Long	Number of files in the Bag, including the tag files
createdAt	DateTime	The date the Bag was created in the ingest server
updatedAt	DateTime	The last time the Bag was updated
replicatingNodes	Set<Node>	Nodes who have successfully replicated the bag
requiredReplications	int	Number of replications required for preservation
bagStorage	StagingStorageModel	Active Staging Information for a bag's data
tokenStorage	StagingStorageModel	Active Staging Information for a bag's tokens

BagStatus

An enumerated type describing the various states a bag can have in its lifetime.

DEPOSITED - The ingest-server has created a DB record for the bag after notification from an intake service
INITIALIZED - The ingest-server has performed necessary tasks before tokenizing (extracting form an archive/file counts and sizes for metadata)
TOKENIZED - The ingest-server has created ACE tokens for a bag and written them to a file for replication
REPLICATING - Replication requests have been created for a bag which are currently in progress
PRESERVED - All replication requests have finished successfully and the number of required replications have been met
ERROR - Somewhere along the line something bad happened

Deprecated Status Enums

(1.3.0-RELEASE) REPLICATED
(1.1.1-RELEASE) STAGED

Code Block

language	js
title	Bag Json Example
collapse	true

        {
            "id": 2,
            "size": 1030783586432,
            "totalFiles": 173357,
            "bagStorage": {
                "active": true,
                "size": 1030783586432,
                "region": 1,
                "totalFiles": 173357,
                "path": "ncar/acadis_20150419",
                "fixities": [
                    {
                        "value": "c9680a2ec9a367f2f218a3d90dbcde3bcff9ed3eb8f7d9c61e525ba1735270da",
                        "algorithm": "SHA-256",
                        "createdAt": "2017-11-30T11:02:50.85746Z"
                    }
                ]
            },
            "tokenStorage": {
                "active": true,
                "size": 1,
                "region": 2,
                "totalFiles": 1,
                "path": "ncar/acadis_201504192015-06-06",
                "fixities": [
                    {
                        "value": "67593e0c4b02a2cbeb1c2440589373654a44b7ef93c889f6290569e92ced21ea",
                        "algorithm": "SHA-256",
                        "createdAt": "2017-11-30T11:02:50.85746Z"
                    }
                ]
            },
            "createdAt": "2016-06-07T12:26:18.13944Z",
            "updatedAt": "2016-06-07T12:26:18.13944Z",
            "name": "acadis_20150419",
            "creator": "admin",
            "depositor": "ncar",
            "status": "PRESERVED",
            "requiredReplications": 3,
            "replicatingNodes": [
                "ncar",
                "umiacs",
                "ucsd"
            ]
        }

Panel

borderStyle	solid
title	Bag API

Deposit Bag

Request: POST /api/bags/
Description: Deposit a Bag in Chronopolis
Request Body: application/json

Code Block

language	js
title	Request Body Example
collapse	true

{
	"name": "bag-example",
    "depositor": "confluence-wiki",
    "location": "bag-example/confluence-wiki",
    "size": 1048576L,
    "totalFiles": 10L,
    "storageRegion": 1L
}

Response Codes: 201 (Success); 400 (invalid); 401 (unauthenticated); 403 (unauthorized); 409 (conflict)
Response Body: Bag

Get All Bags

Request: GET /api/bags
Description: Retrieve a paginated listing of Bags in Chronopolis
Query Parameters:
- name: The name of the bag (partial match
- creator: The name of the user who created the bag
- depositor: The name of the depositor who owns the bag
- region: The Storage Region the Bag is staged in
- createdAfter: Any Bag created after a given date
- createdBefore: Any Bag created before a given date
- updatedAfter: Any Bag updated after a given date
- updatedBefore: Any Bag updated before a given date
- active: Boolean flag - matches any Bag with staged data (an active StagingStorage)
- status: Any Bag with the given BagStatus
- page: The page number to use, starting at 1
- page_size: The number of Bags to retrieve at once
Response Codes: 200 (success); 401; 403
Response Body: Page<Bag>

Get A Single Bag

Request: GET /api/bags/:id
Description: Retrieve a single Bag in Chronopolis by its id
Path Parameters
- id: The id of the bag
Response Codes: 200; 401; 403; 404 (Not Found)

Panel

title	Bag Storage API

Create Staging Storage

Description: Create a StagingStorage object for a given Bag
Request: PUT /api/bags/:id/storage/:type

Request Body: application/json

Code Block

language	js
title	StagingStorage PUT example
collapse	true

{
	"location": "depositor-name/bag-name",
	"storageRegion": 1L,
	"totalFiles": 11L,
	"size": 10,
	"storageUnit": MiB
}

Response Codes: 201, 400, 401, 403

Get A Staging Storage Object

Description: Get a StagingStorage object for a Bag defined by its StorageType
Request: GET /api/bags/:id/storage/:type
Path Parameters:
id: The id of the bag
type: The StorageType to retrieve, BAG or TOKEN
Response Codes: 200, 401, 403, 404

Register Fixity

Description: Create a Fixity for a given StagingStorage
Request: POST /api/bags/:id/storage/:type/fixity
Path Parameters:
id: The id of the bag
type: The StorageType to retrieve, Bag or TOKEN,

Request Body: application/json

Code Block

language	js
title	Fixity POST example
collapse	true

{
	"algorithm": "sha256",
	"value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Response Codes: 200, 400, 401, 403, 409
Response Body: Fixity

Get All Fixities

Description: Get all Fixities for a StagingStorage object on a Bag
Request: GET /api/bags/:id/storage/:type/fixity
Path Parameters:
id: the id of the bag
type: The StorageType to retrieve, BAG or TOKEN
Response Codes: 200, 401, 403
Response Body: Page<Fixity>

Get A Fixity

Description: Get a Fixity for a StagingStorage object on a Bag
Request: GET /api/bags/:id/storage/:type/fixity/:alg
Path Parameters:
id: the id of the bag
type: The StorageType to retrieve, BAG or TOKEN
alg: The name of the algorithm, e.g. sha256
Response Codes: 200, 401, 403, 404
Response Body: Fixity

Panel

title	Bag Token API

Get Bag's Tokens

Description: Retrieve all AceTokens for a Bag
Request: GET /api/bags/:id/tokens
- id: the id of the Bag
Query Parameters
- algorithm: The algorithm used (md5, sha256)
- filename: A list of filenames to search for
Response Codes: 200, 401, 403
Response Body: Page<AceToken>

Register Token For Bag

Description: Register an AceToken with a Bag
Request: POST /api/bags/:id/tokens
- id: The id of the Bag

Request Body: application/json

Code Block

language	js
title	Ace Token POST example
collapse	true

{
	"id": 0,
	"bagId": 1L,
	"round": 12300,
	"proof": "...",
	"imsHost": "ims.umiacs.umd.edu",
	"filename": "data/hello-world.txt"
	"algorithm": "SHA-256",
	"imsService": "SHA-256"
}

Response Codes: 201, 400, 401, 403, 404, 409
Response Body: AceToken

...

Space shortcuts

Page tree

Versions Compared

Old Version 1

New Version Current

Key

Description

Bag

BagStatus

Depositing Bags

Updating Bag Storage

API Description

Bag Model

BagStatus

Deprecated Status Enums

Deposit Bag

Get All Bags

Get A Single Bag

Create Staging Storage

Get A Staging Storage Object

Register Fixity

Get All Fixities

Get A Fixity

Get Bag's Tokens

Register Token For Bag