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.

...

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

...

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

...

borderStyle	solid
title	Bag API

Deposit Bag

...

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)

Create Staging Storage

Description: Create a StagingStorage object for a given Bag
Request: PUT /api/bags/:id/storage/:type
Request Body:
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:
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

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
}

Panel

Code Block

title	Bag Storage API

Panel

title	Bag Token API

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 11

New Version Current

Key

Description

Depositing Bags

Updating Bag Storage

API Description

Bag Model

Deposit Bag

Get All Bags

Get A Single Bag

Get A Staging Storage Object

Register Fixity

Get All Fixities

Get A Fixity

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