Models/Bag

Description

The Bag resource is used to store information about a deposit by a Depositor. When displaying a Bag to the outside world, the Ingest 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

Bag Json Example

        {
            "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"
            ]
        }

Bag API

Deposit Bag

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

Request Body Example

{
	"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)

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

StagingStorage PUT example

{
	"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

Fixity POST example

{
	"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

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

Ace Token POST example

{
	"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

Description

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