Member API

From aptrust
Jump to: navigation, search

The member-api allows depositors to programmatically query for status of events, files, intellectual objects or items in a work queue.

API Basics


These are base URLs for the REST APIApplication Programming Interface:

Request Headers


All API requests require the following headers:

 Header Name  Value  Description
 Content-Type  application/json  This is required for POST and PUT requests. You can omit it on GET requests, but it won't hurt if it's there. This header tells the server that the data in the body of your PUT/POST is in JSON format.
 Accept  application/json  This tells the server to return data in JSON format.
 X-PharosPharos is APTrusts web interface to manage deposits and inspect deposit outcomesETag The entity tag is a hash of the object. The ETag reflects changes only to the contents of an object, not its metadata.-APIApplication Programming Interface-User  An email address.  This should be the email address of a user with a valid account in the APTrust system. Most likely, this is your university/work email address. If the role associated with this email address is Institutional User, you may have access to fewer resources than a user whose role is Institutional Admin.
X-PharosPharos is APTrusts web interface to manage deposits and inspect deposit outcomesETag The entity tag is a hash of the object. The ETag reflects changes only to the contents of an object, not its metadata.-APIApplication Programming Interface-Key  A long string of psuedo-random characters  If you have a user account, but you don't have an API keyAPI key is a code passed in by computer programs calling an application programming interface (API) to identify the calling program, contact [[1]].

Testing


If you like to test basic API requests with a graphical client, try Postman for Chrome. If you prefer to use curl on the command line, you can specify the -H header multiple times. Here's a sample curl request to the items endpoint on the APTrust demo server:

curl -H "Content-Type: application/json" -H "Accept: application/json" -H "X-PharosPharos is APTrusts web interface to manage deposits and inspect deposit outcomesETag The entity tag is a hash of the object. The ETag reflects changes only to the contents of an object, not its metadata.-APIApplication Programming Interface-User: pam@virginia.edu" -H "X-PharosPharos is APTrusts web interface to manage deposits and inspect deposit outcomesETag The entity tag is a hash of the object. The ETag reflects changes only to the contents of an object, not its metadata.-APIApplication Programming Interface-Key: ab8347c1d4f092a8" https://demo.aptrust.org/member-api/v2/items/

Errors


If you don't supply correct user and key credentials, you'll see this:

{"error":"Failed to Login"}

If you run into other errors, contact support@aptrust.org.

API Resources


Event Resource


The Event resource represents a single Premis Event, attached to either and Intellectual Object or a Generic File, and which includes the following fields.

Key Datatype Default Description Example Notes
id integer APTrust's internal ID for an object.  This is for internal use, and APTrust makes no guarantee that it will remain stable or useful to members in any way.
identifier string The unique identifier for an event in the APTrust repository. It is generated by APTrust when the event is created.
event_type string Refers to the type of Premis Event that was created. Event types may be one of the following: 
  • Ingest - Generated when a bag and its associated files are ingested into the system.
  • Validation - Generated when a bag is checked against its bag manifest and checked for validity.
  • Deletion - Generated when a delete request has been made for a bag or its associated files.
  • Fixity Generation - Generated when a bag is ingested as the initial fixity that later checks will be run against.
  • Fixity Check - Generated when a fixity check is run on a bag or its associated files.
  • Identifier Assignment - Generated when an identifier is assigned to the bag or its associated files by S3 for long term storage.
date_time string Date when the premis event was created.
detail string A brief message explaining the purpose of the premis event generation, tailored to the type of event that was created.
outcome string Possible values "Success" or "Failure". In reference to the process that was run in tandem with the event generation, e.g. a successful ingest of a bag into the system will generate an Ingest Premis Event with "Success" in the outcome field.
outcome_detail string MD5 or SHA256 checksum associated with the process that was run in tandem with the event generation.
outcome_information string Additional information pertinent to the individual process that was run in tandem with the event generation. May be empty.
object string Name of the code base or gem that was responsible for the process run in tandem with the event generation.
agent string Source of the object attribute listed above.
created_at datetime Time of creation of object
updated_at datetime Time of last update of object
institution_id integer ID of the institution to which the event belongs.
intellectual_object_id integer ID of the intellectual object to which the event belongs.
generic_file_id integer ID of the generic file to which the event belongs, if it is associated with a generic file. May be empty.
intellectual_object_identifier string Contains the object identifier of the intellectual object to which the event belongs.
generic_file_identifier string ID file identifier of the generic file to which the event belongs, if it is associated with a generic file. May be empty.
old_uuid string Previous identifier of the event if the identifier was a duplicate - something PharosPharos is APTrusts web interface to manage deposits and inspect deposit outcomesETag The entity tag is a hash of the object. The ETag reflects changes only to the contents of an object, not its metadata. no longer allows.
Event Endpoints
Endpoint Method Description Example
 /member-api/v2/events/:generic_file_identifier GET This endpoint returns a list of Premis Events belonging to a particular Generic File. It requires that the user specify the generic_file_identifer as url-encoded, and as part of the base URL. /member-api/v2/events/virginia.edu%2Fvirginia.bag_of_photos%2Fphoto_one.tiff
/member-api/v2/events/:intellectual_object_identifier GET This endpoint returns a list of Premis Events belonging to a particular Intellectual Object. It requires that the user specify the intellectual_object_identifer as url-encoded, and as part of the base URL. /member-api/v2/events/virginia.edu%2Fvirginia.bag_of_photos
/member-api/v2/events/:institution_identifier GET This endpoint returns a list of Premis Events belonging to a particular Institution. It requires that the user specify the institution_identifier as url-encoded, and as part of the base URL. /member-api/v2/events/virginia.edu
Filter Parameters

These endpoints accept the following query string parameters to filter results.

Query Description Example
event_identifier Return only the Premis Event with this exact identifier. The identifier has the format of a Random hex 12f9dc69-e753-435f-b1fd-1d6bc1229957
event_type Return only the Premis Events with this event_type attribute. virginia.edu/virginia.bag_of_photos
intellectual_object_identifier Return only the Premis Events with this exact intellectual object identifier. The identifier has the format of institution domain, followed by a slash, followed by the original bag name, minus the extension.
intellectual_object_identifier_like Return only Premis Events whose intellectual object identifier contains the specified string. See encoding rules above.
generic_file_identifier Return only the Premis Events with this exact generic file identifier. The identifier has the format of institution domain, followed by a slash, followed by the original file name, including the extension. virginia.edu%2Fvirginia.bag_of_photos%2Fphoto_1.tiff
generic_file_identifier_like Return only Premis Events whose generic file identifier contains the specified string.
outcome Return only Premis Events with this outcome - either "success" or "failure".
created_before Return only Premis Events created before the specified timestamp. Use the ISO 8660 datetime format for this parameter. Other formats may work, but are not guaranteed. created_before=2016-01-27T00:00:00Z.
created_after Return only Premis Events created after the specified timestamp. Use the ISO 8660 datetime format for this parameter created_after=2016-01-27T00:00:00Z.
page Return page X of results, where X is an integer. If this is not specified, it defaults to 1.
per_page The number of items to include in the page of results. If this is not specified, it defaults to 10.
JSON Response

A sample JSON response appears below, and includes the following:

  • count is the number of events matching your query.
  • next is the URL for the next page of results. When this is null, there is no next page. 
  • previous is the URL for the previous page of results. When this is null, there is no previous page.
  • results is an array of Premis Event records, described on the Event Resource page.
{
    "count": 6,
    "next": "http://localhost:3000/member-api/v2/events/virginia.edu%2Fvirginia.edu_dc3acb8?page=3&per_page=2",
    "previous": "http://localhost:3000/member-api/v2/events/virginia.edu%2Fvirginia.edu_dc3acb8?page=1&per_page=2",
    "results": [
        {
            "id": 55506,
            "identifier": "12f9dc69-e753-435f-b1fd-1d6bc1229957",
            "event_type": identifier_assignment",
            "date_time": "2014-11-24T18:56:11.348Z",
            "outcome_detail": "https://s3.amazonaws.com/aptrust.preservation.storage/ 651f59cd-0cc0-4dd2-985a-a54825f0fc9e",
            "detail": "Assigned new storage URL identifier",  
            "outcome_information": "Generated with ruby SecureRandom.uuid()",
            "outcome": "success",
            "object": "Ruby 2.3.1",
            "agent": "Http://www.ruby-doc.org/",
            "institution_id": 123,
            "intellectual_object_id": 123456,
            "generic_file_id": 123456789,
            "created_at": "2014-11-24T18:56:11.348Z",
            "updated_at": "2014-11-24T19:17:03.715Z",
            "intellectual_object_identifier": "virginia.edu/va.edu_dc",
            "generic_file_identifier": "virginia.edu/va.edu_dc/photo.tiff",
            "old_uuid": ""  
        },
        {
            "id": 55507,
            "identifier": "12f9dc69-e753-435f-b1fd-1d6bc1229958",
            "event_type": "fixity check",
            "date_time": "2014-11-24T18:56:11.348Z",
            "outcome_detail": "md5:7bd2624da5617e1f3125ba14a241fe84",
            "detail": "Fixity check against registered hash",  
            "outcome_information": "Fixity matches",
            "outcome": "success",
            "object": "Go language cryptohash",
            "agent": "Http://golang.org/",
            "institution_id": 123,
            "intellectual_object_id": 123456,
            "generic_file_id": 123456789,
            "created_at": "2014-11-24T18:56:11.348Z",
            "updated_at": "2014-11-24T19:17:03.715Z",
            "intellectual_object_identifier": "virginia.edu/va.edu_dc",
            "generic_file_identifier": "virginia.edu/va.edu_dc/photo.tiff",
            "old_uuid": ""
        },
    ]
}

File Resource


The File resource represents a single generic file, which includes the following fields: 
Key Datatype Description
id integer Internal ID for this object. This is for internal use, and APTrust makes no guarantee that it will remain stable or useful to members in any way.
intellectual_object_id integer Contains the APTrust id of the intellectual object to which the generic file belongs
identifier string Unique identifier for this file in the APTrust repository. This is composed as <institutions_domain_name>/<intellectual_object_identifier_parent_object>/<individual_file_name>

This is the identifier to use when looking for a specific file

file_format string Refers to the format of the generic file, e.g. application/pdf.
size integer Refers to the size, in bytes, of the generic file
uri string Contains the URL for the actual location of the file in Amazon's S3 storage. 
state string 'A' for active, 'D' is for deleted. An active bag is one that is still in the repository. Deleted bags have been deleted from the repository by some user. You can find out when a bag was deleted and who requested the deletion by querying the Items endpoint and filtering down to bags with a specific identifier and action=Delete.
created_at datetime Time of creation
updated_at datetime Time of last update
 last_fixity_check  datetime Time of last fixity check.
File Endpoints
Endpoint Method Description Example
/member-api/v2/files/:intellectual_object_identifier GET This endpoint returns a list of Generic Files belonging to a particular Intellectual Object. It requires that the user specify the intellectual_object_identifer as url-encoded, and as part of the base URL. /member-api/v2/files/virginia.edu%2Fvirginia.bag_of_photos
Filter Parameters
Query Description Example
identifier Return only the Generic Files with this exact identifier. The identifier has the format of institution domain, followed by a slash, followed by the original file name, including the extension. When using this parameter, it has to be url-encoded, like a slash as %2F. For example "virginia.edu/virginia.bag_of_photos/photo_1.tiff".becomes "virginia.edu%2Fvirginia.bag_of_photos%2Fphoto_1.tiff" virginia.edu%2Fvirginia.bag_of_photos%2Fphoto_1.tiff
identifier_like Return only Generic Files whose identifier contains the specified string. See encoding rules above. 
uri Return only the Generic Files with this exact URI.
uri_like Return only Generic Files whose URI contains the specified string
file_format Return only Generic Files that have the specified file format.
created_before Return only Generic Files created before the specified timestamp. Use the ISO 8660 datetime format for this parameter. Other formats may work, but are not guaranteed. For example, to retrieve objects created before Jan. 27, 2016, use  created_before=2016-01-27T00:00:00Z.
created_after Return only Generic Files created after the specified timestamp. Use the ISO 8660 datetime format for this parameter created_after=2017-01-27T00:00:00Z.
updated_before Return only Generic Files updated before the specified timestamp. Use the ISO 8660 datetime format for this parameter updated_before=2016-01-27T00:00:00Z.
updated_after Return only Generic Files updated since the specified timestamp. Use the ISO 8660 datetime format for this parameter updated_after=2017-01-27T00:00:00Z.
page Return page X of results, where X is an integer. If this is not specified, it defaults to 1. page=10
per_page The number of items to include in the page of results. If this is not specified, it defaults to 10. per_page=12
JSON Response

A sample JSON response appears below, and includes the following:

  • count is the number of files matching your query.
  • next is the URL for the next page of results. When this is null, there is no next page. 
  • previous is the URL for the previous page of results. When this is null, there is no previous page.
  • results is an array of Generic File records, described on the File Resource page.
    {
        "count": 15,
        "next": "http://localhost:3000/member-api/v2/files/virginia.edu%2Fvirginia.edu_dc3acb8?page=3&per_page=4",
        "previous": "http://localhost:3000/member-api/v2/files/virginia.edu%2Fvirginia.edu_dc3acb8?page=1&per_page=4",
        "results": [
            {
                "id": 55506,
                "file_format": "application/pdf",
                "uri": "https://s3.amazonaws.com/aptrust.preservation.storage/1234abc-5678def",
                "size": 23432,  
                "identifier": "virginia.edu/virginia.edu_dc3acb8/data_one.pdf",
                "intellectual_object_id": 123456,
                "created_at": "2014-11-24T18:56:11.348Z",
                "updated_at": "2014-11-24T19:17:03.715Z",
                "state": "A",
                "intellectual_object_identifier": "virginia.edu/virginia.edu_dc3acb8",
                "last_fixity_check": "2017-01-31T22:02:37.8719706Z"  
            },
            {
                "id": 55507,
                "file_format": "application/pdf",
                "uri": "https://s3.amazonaws.com/aptrust.preservation.storage/1234abc- 5678ghi",
                "size": 23432,  
                "identifier": "virginia.edu/virginia.edu_dc3acb8/data_two.pdf",
                "intellectual_object_id": 123456,
                "created_at": "2014-11-24T18:56:11.348Z",
                "updated_at": "2014-11-24T19:17:03.715Z",
                "state": "A",
                "intellectual_object_identifier": "virginia.edu/virginia.edu_dc3acb8"
            },
            {
                "id": 55508,
                "file_format": "application/pdf",
                "uri": "https://s3.amazonaws.com/aptrust.preservation.storage/1234abc-5678jkl",
                "size": 23432,  
                "identifier": "virginia.edu/virginia.edu_dc3acb8/data_three.pdf",
                "intellectual_object_id": 123456,
                "created_at": "2014-11-24T18:56:11.348Z",
                "updated_at": "2014-11-24T19:17:03.715Z",
                "state": "A",
                "intellectual_object_identifier": "virginia.edu/virginia.edu_dc3acb8",
                "last_fixity_check": "2017-01-31T22:02:37.8719706Z"  
            },
            {
                "id": 55509,
                "file_format": "application/pdf",
                "uri": "https://s3.amazonaws.com/aptrust.preservation.storage/1234abc-5678mno",
                "size": 23432,  
                "identifier": "virginia.edu/virginia.edu_dc3acb8/data_four.pdf",
                "intellectual_object_id": 123456,
                "created_at": "2014-11-24T18:56:11.348Z",
                "updated_at": "2014-11-24T19:17:03.715Z",
                "state": "A",
                "intellectual_object_identifier": "virginia.edu/virginia.edu_dc3acb8",
                "last_fixity_check": "2017-01-31T22:02:37.8719706Z"  
            }
        ]
    }
    

Item Resource


Item Endpoints
Endpoint Method Description Example
 /member-api/v2/items GET This endpoint returns a list of items in the APTrust work queue, including items where the work has been completed. Use this endpoint to check the status of any of the following: 
  • bag ingest requests
  • restoration requests
  • deletion requests
  • requests to send items to DPN
Filter Parameters

The endpoint accepts the following query string parameters to filter results. If you are periodically checking on the status of items in the work queue, the updated_after param is your best friend!

  • updated_after - Return only items updated since the specified timestamp. Use the ISO 8660 datetime format for this parameter. Other formats may work, but are not guaranteed. For example, to retrieve items updated since Jan. 27, 2016, use updated_since=2016-01-27T00:00:00Z. Note that items will be updated several times as they pass through the multiple steps of the ingest process.
  • updated_before - Return only items updated before the specified timestamp. Use the ISO 8660 datetime format for this parameter (see updated_after).
  • created_before - Return only items created before the specified timestamp. Use the ISO 8660 datetime format for this parameter (see updated_after).
  • created_after - Return only items created after the specified timestamp. Use the ISO 8660 datetime format for this parameter (see updated_after).
  • bag_date - Return only items with the exact bag_date specified. Use the ISO 8660 datetime format for this parameter (see updated_after).
  • name - Return only items with the exact tar file name. 
  • name_contains - Return only items whose tar file name contains the specified string. This can be useful if you've uploaded a multi-part bag with tar files my_bag.b001.of099.tar through my_bag.b099.of099.tar and you want to get the status of all the parts.
  • etag - Return only items with the exact etag specified.
  • etag_contains - Return only items whose etag contains the specified string.
  • item_action - Return only items having the specified action. The values for this parameter should be all lower-case. Actions include "ingest", "fixity check", "restore", "delete" and "dpn". The Item Resource page includes a definition of each action. [Note: This parameter was called "action" in the initial release of the APIApplication Programming Interface. We changed it because "action" is a reserved parameter in Rails.]
  • stage - Return only items having the specified stage. Stages include "Requested", "Receive", "Fetch", "Unpack", "Validate", "Store", "Record", "Cleanup" and "Resolve". The Item Resource page includes a definition of each stage.
  • status - Return only items having the specified status. Status values include "Pending", "Started", "Success", "Fail", "Cancelled". The Item Resource page includes a definition of each status.
  • object_identifier - Return only items with the exact object identifier specified. Useful for finding all items associated with a specific object.
  • object_identifier_contains - Return only items whose object identifier contains the specified string. Useful for finding all items associated with groupings of objects.
  • file_identifier - Return only items with the exact file identifier specified. Useful for finding all items associated with a specific file.
  • file_identifier_contains - Return only items whose file identifier contains the specified string. Useful for finding all items associated with groupings of files.
  • access - Return only items with a specified level of access (such as consortial). Access is determined through the access level of the associated object. If an object has not yet been associated, access defaults to restricted.
  • queued - Can be set to true or false. When true, returns only items that have been added to the NSQ work queue, when false, returns only items that have not been queued.
  • page - Return page X of results, where X is an integer. If this is not specified, it defaults to 1.
  • per_page - The number of items to include in the page of results. If this is not specified, it defaults to 10.


JSON Response Format

A sample JSON response appears below, and includes the following:

  • count is the number of items matching your query.
  • next is the URL for the next page of results. When this is null, there is no next page. 
  • previous is the URL for the previous page of results. When this is null, there is no previous page.
  • results is an array of Item objects, described on the Item Resource page.
    {
        "count": 5750,
        "next": "http://test.aptrust.org/member-api/v2/items/?page=11&per_page=5",
        "previous": "http://test.aptrust.org/member-api/v2/items/?page=9&per_page=5",
        "results": [
            [
                {
                    "id": 130591,
                    "created_at": "2014-11-24T18:56:11.348Z",
                    "updated_at": "2014-11-24T19:17:03.715Z",
                    "name": "ncsu.1840.16-102.tar",
                    "etag": "c8b80aadba6adabff06d35e029175daf",
                    "bucket": "aptrust.receiving.test.ncsu.edu",
                    "user": "system@aptrust.org",
                    "note": "No problems",
                    "action": "Ingest",
                    "stage": "Record",
                    "status": "Success",
                    "outcome": "Success",
                    "bag_date": "2014-10-27T14:46:34.000Z",
                    "date": "2014-11-24T19:14:55.751Z",
                    "retry": false,
                    "needs_admin_review": false,
                    "queued_at": null,
                    "size": 463729,
                    "stage_started_at": null,
                    "institution_id": 345172,
                    "object_identifier": "ncsu.edu/ncsu.1840.16-102",
                    "intellectual_object_id": 859375938294,
                    "generic_file_identifier": null,
                    "generic_file_id": null
                },
                {
                    "id": 130592,
                    "created_at": "2014-11-24T18:56:11.550Z",
                    "updated_at": "2014-11-24T19:17:11.902Z",
                    "name": "ncsu.1840.16-1020.tar",
                    "etag": "f5cdd9cbaf4808c7a618905084134474",
                    "bucket": "aptrust.receiving.test.ncsu.edu",
                    "user": "system@aptrust.org",
                    "note": "No problems",
                    "action": "Ingest",
                    "stage": "Record",
                    "status": "Success",
                    "outcome": "Success",
                    "bag_date": "2014-10-27T14:46:34.000Z",
                    "date": "2014-11-24T19:15:04.479Z",
                    "retry": false,
                    "needs_admin_review": false,
                    "queued_at": null,
                    "size": 463729,
                    "stage_started_at": null,
                    "institution_id": 345172,
                    "object_identifier": "ncsu.edu/ncsu.1840.16-1020",
                    "intellectual_object_id": 859375938295,
                    "generic_file_identifier": null,
                    "generic_file_id": null
                },
                {
                    "id": 130595,
                    "created_at": "2014-11-24T18:56:12.252Z",
                    "updated_at": "2014-11-24T19:17:31.858Z",
                    "name": "ncsu.1840.16-1023.tar",
                    "etag": "fa28cd2c9bef9515210c89fdcb49e80b",
                    "bucket": "aptrust.receiving.test.ncsu.edu",
                    "user": "system@aptrust.org",
                    "note": "No problems",
                    "action": "Ingest",
                    "stage": "Record",
                    "status": "Success",
                    "outcome": "Success",
                    "bag_date": "2014-10-27T14:46:35.000Z",
                    "date": "2014-11-24T19:15:23.855Z",
                    "retry": false,
                    "needs_admin_review": false,
                    "queued_at": null,
                    "size": 463729,
                    "stage_started_at": null,
                    "institution_id": 345172,
                    "object_identifier": "ncsu.edu/ncsu.1840.16-1023",
                    "intellectual_object_id": 859375938296,
                    "generic_file_identifier": null,
                    "generic_file_id": null
                },
                {
                    "id": 130599,
                    "created_at": "2014-11-24T18:56:13.049Z",
                    "updated_at": "2014-11-24T19:17:44.847Z",
                    "name": "ncsu.1840.16-1027.tar",
                    "etag": "ab4681a9e3819cf91e21f3243b524ea6",
                    "bucket": "aptrust.receiving.test.ncsu.edu",
                    "user": "system@aptrust.org",
                    "note": "No problems",
                    "action": "Ingest",
                    "stage": "Record",
                    "status": "Success",
                    "outcome": "Success",
                    "bag_date": "2014-10-27T14:46:36.000Z",
                    "date": "2014-11-24T19:15:37.512Z",
                    "retry": false,
                    "needs_admin_review": false,
                    "queued_at": null,
                    "size": 463729,
                    "stage_started_at": null,
                    "institution_id": 345172,
                    "object_identifier": "ncsu.edu/ncsu.1840.16-1027",
                    "intellectual_object_id": 859375938297,
                    "generic_file_identifier": null,
                    "generic_file_id": null
                },
                {
                    "id": 130602,
                    "created_at": "2014-11-24T18:56:13.656Z",
                    "updated_at": "2014-11-24T19:18:16.023Z",
                    "name": "ncsu.1840.16-103.tar",
                    "etag": "654f0928c54ff5487635638a2970af2f",
                    "bucket": "aptrust.receiving.test.ncsu.edu",
                    "user": "system@aptrust.org",
                    "note": "No problems",
                    "action": "Ingest",
                    "stage": "Record",
                    "status": "Success",
                    "outcome": "Success",
                    "bag_date": "2014-10-27T14:46:36.000Z",
                    "date": "2014-11-24T19:16:07.414Z",
                    "retry": false,
                    "needs_admin_review": false,
                    "queued_at": null,
                    "size": 463729,
                    "stage_started_at": null,
                    "institution_id": 345172,
                    "object_identifier": "ncsu.edu/ncsu.1840.16-103",
                    "intellectual_object_id": 859375938298,
                    "generic_file_identifier": null,
                    "generic_file_id": null
                }
            ]
        ]
    }
    

Object Resource


The Object resource represents a single intellectual object, which includes the following fields: 

  • id - (integer) APTrust's internal ID for this object. This is for internal use, and APTrust makes no guarantee that it will remain stable or useful to members in any way.
  • title - (string) The title of the intellectual object, taken from the Title tag of the aptrust-info.txt tag file.
  • description - (string) The description of the bag, taken from the Title tag of the aptrust-info.txt tag file. This may be an empty string, as the Description tag contents are optional.
  • access - (string) The access rights to this object, as specified in the Access tag of the aptrust-info.txt tag file. This will be one of the following:
    • consortia - Any APTrust member may view information about this object in the APTrust Web UI.
    • institution - Only users and admins from the object's owning institution can view information about this object.
    • restricted - Users and admins from the object's institution can see that the object is in the repository, but some details about the object are accessible to institutional admins only.
  • bag_name - (string) The name of the bag. This matches the name of the tar file uploaded into the receiving bucket, minus the .tar or .bag00x.of00x.tar extension.
  • identifier - (string) The unique identifier for this bag in the APTrust repository. This is composed of the depositing institution's domain name, plus a slash, plus the bag name. This is the identifier to use when you are looking for a specific bag.
  • state - (string) 'A' for active, 'D' is for deleted. An active bag is one that is still in the repository. Deleted bags have been deleted from the repository by some user. You can find out when a bag was deleted and who requested the deletion by querying the Items endpoint and filtering down to bags with a specific identifier and action=Delete.
  • alt_identifier - (array of strings) Although this is an array of strings, it will always contain either zero or one element. If you sent a value for the Internal-Sender-Identifier field in your bag_info.txt file, that value will appear as the first item in the alt_identifier array.
  • etag - (string) The etag of the tar file you uploaded that eventually became this intellectual object. S3 returns the etag on successful upload. For single-part uploads, the etag is the md5 digest of the tar file. For larger, multipart uploads, the etag looks like an md5 checksum, followed by a dash and the number of parts in the multipart upload. Amazon has some documentation on that here, and you'll find a good overview of how multipart etags are calculated hereThe purpose of including the etag in the intellectual object JSON is to help you know which uploaded tar file we used to build your intellectual object. See the ingest documentation for more info about what happens when you upload multiple versions of the same bag.
  • created_at - (datetime) When this object was created.
  • updated_at - (datetime) When this object was last updated.
  • institution_id - (integer) Contains the APTrust id of the institution to which the object belongs.
  • dpn_uuid - (string) Contains the UUID of the object in DPN if it has been sent to DPN and successfully ingested.
Object Endpoints
Object Restoration
Endpoint Method Description Example
/member-api/v2/objects/:intellectual_object_identifier/restore GET Allows a user to specify an intellectual object (via identifier) to be restored. It requires that the user specify the intellectual_object_identifer as url-encoded, and as part of the base URL. If the request is successful, the endpoint will return a newly created work item with specifics pertaining to the restoration request.  /member-api/v2/objects/virginia.edu%2Fvirginia.bag_of_photos/restore
Filter Parameters

The endpoint accepts the following query string parameters to filter results.

Query Description Example
description Return only the Intellectual Objects with this exact description.
description_like Return only Intellectual Objects whose description contains the specified string.
identifier Return only the Intellectual Objects with this exact identifier. The identifier has the format of institution domain, followed by a slash, followed by the original bag name, minus the extension. For example "virginia.edu/virginia.bag_of_photos". When you include this parameter, you must url-encode the slash as %2F. virginia.edu/virginia.bag_of_photos
identifier_like Return only Intellectual Objects whose identifier contains the specified string. See encoding rules above. 
alt_identifier Return only the Intellectual Objects with this exact alternative identifier.
alt_identifier_like Return only Intellectual Objects whose alternative identifier contains the specified string.
etag Return only the Intellectual Objects with this exact etag.
etag_like Return only Intellectual Objects whose etag contains the specified string.
bag_name Return only the Intellectual Object with this exact bag name. The name has the format of institution domain, followed by a slash, followed by the bag name. For example, "virginia.edu/virginia.bag_of_photos.tar". When you include this parameter, you must url-encode the slash as %2F.
bag_name_like Return only those Intellectual Objects whose bag name contains the specified string. See encoding rules above.
created_before Return only Intellectual Objects created before the specified timestamp. Use the ISO 8660 datetime format for this parameter. Other formats may work, but are not guaranteed. For example, to retrieve objects created before Jan. 27, 2016, use created_before=2016-01-27T00:00:00Z.
created_after Return only Intellectual Objects created after the specified timestamp. Use the ISO 8660 datetime format for this parameter (see created_before).
updated_before Return only Intellectual Objects updated before the specified timestamp. Use the ISO 8660 datetime format for this parameter (see created_before).
updated_after Return only Intellectual Objects updated since the specified timestamp. Use the ISO 8660 datetime format for this parameter (see created_before)
access Return only Intellectual Objects with the specified level of access (such as "consortial").
state Return only Intellectual Objects with the specified state. For example, to retrieve only deleted objects use state=D. To retrieve only active objects use state=A.
file_format Return only Intellectual Objects that have one or more associated generic files with the specified file format.
page Return page X of results, where X is an integer. If this is not specified, it defaults to 1.
per_page The number of items to include in the page of results. If this is not specified, it defaults to 10.

JSON Response

A sample JSON response appears below, and will include the following:

  • status is the status of your request. It will either be "error" if your item cannot be queued for restoration or "ok" if your request was successful.
  • message is the explanation of the status if the status was returned as "error". 
  • work_item_id is the id of the work item if the request was successful. If the request was unsuccessful it will be "0".
    Results for a failed attempt:
    {
        "status": "error",
        "message": "This item has been deleted and cannot be queued for restoration.",
        "work_item_id": 0
    } 
    
    Results for a successful attempt:
    {
        "status": "ok",
        "message": "Your item has been queued for restoration.",
        "work_item_id": 123456
    }
    
Object Endpoint
Endpoint Method Description Example
/member-api/v2/objects/ GET This endpoint returns a list of Intellectual Objects belonging to your institution. Intellectual Objects are usually fully ingested bags, though when bags are uploaded in multiple parts, the Intellectual Object may appear before all of the component bags are fully ingested.
Filter Parameters

The endpoint accepts the following query string parameters to filter results.

  • description - Return only the Intellectual Objects with this exact description.
  • description_like - Return only Intellectual Objects whose description contains the specified string.
  • identifier - Return only the Intellectual Objects with this exact identifier. The identifier has the format of institution domain, followed by a slash, followed by the original bag name, minus the extension. For example "virginia.edu/virginia.bag_of_photos". When you include this parameter, you must url-encode the slash as %2F.
  • identifier_like - Return only Intellectual Objects whose identifier contains the specified string. See encoding rules above. 
  • alt_identifier - Return only the Intellectual Objects with this exact alternative identifier.
  • alt_identifier_like - Return only Intellectual Objects whose alternative identifier contains the specified string.
  • etag - Return only the Intellectual Objects with this exact etag.
  • etag_like - Return only Intellectual Objects whose etag contains the specified string.
  • bag_name - Return only the Intellectual Object with this exact bag name. The name has the format of institution domain, followed by a slash, followed by the bag name. For example, "virginia.edu/virginia.bag_of_photos.tar". When you include this parameter, you must url-encode the slash as %2F.
  • bag_name_like - Return only those Intellectual Objects whose bag name contains the specified string. See encoding rules above.
  • created_before - Return only Intellectual Objects created before the specified timestamp. Use the ISO 8660 datetime format for this parameter. Other formats may work, but are not guaranteed. For example, to retrieve objects created before Jan. 27, 2016, use created_before=2016-01-27T00:00:00Z.
  • created_after - Return only Intellectual Objects created after the specified timestamp. Use the ISO 8660 datetime format for this parameter (see created_before).
  • updated_before - Return only Intellectual Objects updated before the specified timestamp. Use the ISO 8660 datetime format for this parameter (see created_before).
  • updated_after - Return only Intellectual Objects updated since the specified timestamp. Use the ISO 8660 datetime format for this parameter (see created_before).
  • access - Return only Intellectual Objects with the specified level of access (such as "consortial").
  • state - Return only Intellectual Objects with the specified state. For example, to retrieve only deleted objects use state=D. To retrieve only active objects use state=A.
  • file_format - Return only Intellectual Objects that have one or more associated generic files with the specified file format.
  • page - Return page X of results, where X is an integer. If this is not specified, it defaults to 1.
  • per_page - The number of items to include in the page of results. If this is not specified, it defaults to 10.

JSON Response Format

A sample JSON response appears below, and includes the following:

  • count is the number of items matching your query.
  • next is the URL for the next page of results. When this is null, there is no next page. 
  • previous is the URL for the previous page of results. When this is null, there is no previous page.
  • results is an array of Intellectual Object records, described on the Object Resource page.
    {
        "count": 15,
        "next": "http://localhost:3000/member-api/v2/objects/?page=3&per_page=5&state=A",
        "previous": "http://localhost:3000/member-api/v2/objects/?page=1&per_page=5&state=A",
        "results": [
            {
                "id": "changeme:55506",
                "title": "Roots of Alternative Medicine",
                "description": "",
                "access": "consortia",
                "bag_name": "virginia.edu_dc3acb8",
                "identifier": "virginia.edu/virginia.edu_dc3acb8",
                "state": "A",
                "alt_identifier": ["med:377892276"],
                "etag": "987654321fedcba0123456789",
                "created_at": "2014-11-24T18:56:11.348Z",
                "updated_at": "2014-11-24T19:17:03.715Z",
                "institution_id": 345168,
                "dpn_uuid": null
            },
            {
                "id": "changeme:55511",
                "title": "Test Bag For IU",
                "description": "",
                "access": "consortia",
                "bag_name": "iu.edu.testbag1",
                "identifier": "test.edu/iu.edu.testbag1",
                "state": "A",
                "alt_identifier": [],
                "etag": "987654321fedcba0123400000",
                "created_at": "2014-11-24T18:56:11.348Z",
                "updated_at": "2014-11-24T19:17:03.715Z",
                "institution_id": 345168,
                "dpn_uuid": null
            },
            {
                "id": "changeme:55517",
                "title": "Our Friend the Beaver",
                "description": "",
                "access": "consortia",
                "bag_name": "test_oftb_19820116",
                "identifier": "test.edu/test_oftb_19820116",
                "state": "A",
                "alt_identifier": ["0089771632555"],
                "etag": "987654321fedcba0123488888",
                "created_at": "2014-11-24T18:56:11.348Z",
                "updated_at": "2014-11-24T19:17:03.715Z",
                "institution_id": 345168,
                "dpn_uuid": null
            },
            {
                "id": "changeme:55522",
                "title": "APTrust/DPN Test Bag 3",
                "description": "",
                "access": "consortia",
                "bag_name": "test.edu.bag3",
                "identifier": "test.edu/test.edu.bag3",
                "state": "A",
                "alt_identifier": [],
                "etag": "987654321fedcba0123455555",
                "created_at": "2014-11-24T18:56:11.348Z",
                "updated_at": "2014-11-24T19:17:03.715Z",
                "institution_id": 345168,
                "dpn_uuid": null
            },
            {
                "id": "changeme:55525",
                "title": "APTrust/DPN Test Bag 4",
                "description": "",
                "access": "consortia",
                "bag_name": "test.edu.bag4",
                "identifier": "test.edu/test.edu.bag4",
                "state": "A",
                "alt_identifier": [],
                "etag": "987654321fedcba0123444444",
                "created_at": "2014-11-24T18:56:11.348Z",
                "updated_at": "2014-11-24T19:17:03.715Z",
                "institution_id": 345168,
                "dpn_uuid": null
            }
        ]
    }
    
Send-to-DPN endpoint
Endpoint Method Description Example
/member-api/v2/objects/:intellectual_object_identifier/dpn GET This endpoint allows a user to specify an intellectual object (via identifier) to be queued for DPN. It requires that the user specify the intellectual_object_identifer as url-encoded, and as part of the base URL. If the request is successful, the endpoint will return a newly created work item with specifics pertaining to the DPN request. If the request is unsuccessful, the user will return an error message with an explanation.  /member-api/v2/objects/virginia.edu%2Fvirginia.bag_of_photos/dpn

Parameters

JSON Response

A sample JSON response appears below, and may include the following:

  • status is the status of your request. It will either be "error" if your item cannot be queued for DPN or it will not be part of the JSON response.
  • message is the explanation of the status if the status was returned as "error". It will not be part of the JSON response if the request was successful.
    Results for a failed attempt:
    {
        "status": "error",
        "message": "We are not currently sending items to DPN."
    } 
    
    Results for a successful attempt:
    {
        "id": 130591,
        "created_at": "2014-11-24T18:56:11.348Z",
        "updated_at": "2014-11-24T19:17:03.715Z",
        "name": "ncsu.1840.16-102.tar",
        "etag": "c8b80aadba6adabff06d35e029175daf",
        "bucket": "aptrust.receiving.test.ncsu.edu",
        "user": "system@aptrust.org",
        "note": "Requested item be sent to DPN",
        "action": "DPN",
        "stage": "Requested",
        "status": "Pending",
        "outcome": "Not started",
        "bag_date": "2014-10-27T14:46:34.000Z",
        "date": "2014-11-24T19:14:55.751Z",
        "retry": true,
        "needs_admin_review": false,
        "queued_at": null,
        "size": null,
        "stage_started_at": null,
        "institution_id": 345172,
        "object_identifier": "ncsu.edu/ncsu.1840.16-102",
        "intellectual_object_id": 859375938294,
        "generic_file_identifier": null,
        "generic_file_id": null
    }
    

DPN Bag Resource


The DPN Bag resource represents a single DPN Bag and is associated with a specific intellectual object that has been sent to DPN. Each DPN bag includes the following fields.

Key Datatype Default Description Example Notes
id integer APTrust's internal ID for an object.  This is for internal use, and APTrust makes no guarantee that it will remain stable or useful to members in any way.
institution_id integer ID of the institution to which the event belongs.
object_identifier string Contains the object identifier of the intellectual object to which the event belongs.
dpn_identifier string Contains the identifier that was assigned to the DPN object upon ingest into DPN.
dpn_size bigint
node_1 string The primary node storing the DPN object. Will be one of the following options:
  • chron (indicates storage in Chronopolis)
  • hathi (indicates storage in HathiTrust)
  • sdr (indicates storage in Stanford Digital Repository)
  • tdr (indicates storage in Texas Digital Repositories)
  • aptrust (indicates storage in APTrust)
All of the node attributes have the same list of possible options.
node_2 string The secondary node storing the DPN object
node_3 string The tertiary node storing the DPN object
dpn_created_at datetime Time of creation of actual DPN object in DPN
dpn_updated_at datetime Time of last update of actual DPN object in DPN
created_at datetime Time of creation of DPN bag object in PharosPharos is APTrusts web interface to manage deposits and inspect deposit outcomesETag The entity tag is a hash of the object. The ETag reflects changes only to the contents of an object, not its metadata.
updated_at datetime Time of last update of DPN bag object in PharosPharos is APTrusts web interface to manage deposits and inspect deposit outcomesETag The entity tag is a hash of the object. The ETag reflects changes only to the contents of an object, not its metadata.
DPN Bag Endpoints
Index Endpoint Method Description Example
 /member-api/v2/dpn_bags/ GET This endpoint returns a list of all of the DPN bags a user has access to - for non-APTrust technical staff this will only be the DPN bags associated with the user's own institution. /member-api/v2/dpn_bags
Filter Parameters

This endpoint accepst the following query string parameters to filter results.

Query Description Example
object_identifier Returns only the DPN Bag with this exact object identifier. object_identifier=virginia.edu/virginia.bag_of_photos
dpn_identifier Return only the DPN Bag with this exact DPN identifier dpn_identifier=12f9dc69-e753-435f-b1fd-1d6bc1229957
created_before Return only DPN Bags created before the specified timestamp (as compared to the dpn_created_at attribute). Use the ISO 8660 datetime format for this parameter. Other formats may work, but are not guaranteed. created_before=2016-01-27T00:00:00Z.
created_after Return only DPN Bags created after the specified timestamp (as compared to the dpn_created_at attribute). Use the ISO 8660 datetime format for this parameter. Other formats may work, but are not guaranteed. created_after=2016-01-27T00:00:00Z.
updated_before Return only DPN Bags updated before the specified timestamp (as compared to the dpn_updated_at attribute). Use the ISO 8660 datetime format for this parameter. Other formats may work, but are not guaranteed. updated_before=2016-01-27T00:00:00Z.
updated_after Return only DPN Bags updated after the specified timestamp (as compared to the dpn_updated_at attribute). Use the ISO 8660 datetime format for this parameter. Other formats may work, but are not guaranteed. updated_after=2016-01-27T00:00:00Z.
page Return page X of results, where X is an integer. If this is not specified, it defaults to 1.
per_page The number of items to include in the page of results. If this is not specified, it defaults to 10.
JSON Response

A sample JSON response appears below, and includes the following:

  • count is the number of DPN bags matching your query.
  • next is the URL for the next page of results. When this is null, there is no next page. 
  • previous is the URL for the previous page of results. When this is null, there is no previous page.
  • results is an array of DPN Bag records, described on the DPN Bag page.
{
    "count": 6,
    "next": "http://localhost:3000/member-api/v2/dpn_bags/?page=3&per_page=2",
    "previous": "http://localhost:3000/member-api/v2/dpn_bags/?page=1&per_page=2",
    "results": [
        {
            "id": 55598,
            "institution_id": 12,
            "object_identifier": "virginia.edu/virginia.bag_of_photos",
            "dpn_identifier": "12f9dc69-e753-435f-b1fd-1d6bc1229957",
            "dpn_size": 484362998,
            "node_1": "aptrust",
            "node_2": "chron",
            "node_3": "tdr",  
            "dpn_created_at": "2014-11-24T18:56:11.348Z",
            "dpn_updated_at": "2014-11-24T19:17:03.715Z",
            "created_at": "2014-11-24T18:56:11.348Z",
            "updated_at": "2014-11-24T19:17:03.715Z",  
        },
        {
            "id": 55599,
            "institution_id": 12,
            "object_identifier": "virginia.edu/virginia.bag_of_photos_2",
            "dpn_identifier": "12f9dc69-e753-435f-b1fd-1d6bc1229985",
            "dpn_size": 484362916,
            "node_1": "aptrust",
            "node_2": "hathi",
            "node_3": "sdr",  
            "dpn_created_at": "2014-11-24T18:56:11.348Z",
            "dpn_updated_at": "2014-11-24T19:17:03.715Z",
            "created_at": "2014-11-24T18:56:11.348Z",
            "updated_at": "2014-11-24T19:17:03.715Z", 
        }
    ]
}
Show Endpoint Method Description Example
/member-api/v2/dpn_bags/:id GET This endpoint returns a specific DPN bag by its internal PharosPharos is APTrusts web interface to manage deposits and inspect deposit outcomesETag The entity tag is a hash of the object. The ETag reflects changes only to the contents of an object, not its metadata. ID. /member-api/v2/dpn_bags/15
JSON Response

A sample JSON response appears below, and may include the following:

  • status is the status of your request. It will either be "error" if your item cannot be queued for DPN or it will not be part of the JSON response.
  • message is the explanation of the status if the status was returned as "error". It will not be part of the JSON response if the request was successful.
    Results for a failed attempt:
    {
        "status": "not found",
        "message": "That DPN Bag could not be found."
    } 
    
    Results for a successful attempt:
    {
        "id": 55599,
        "institution_id": 12,
        "object_identifier": "virginia.edu/virginia.bag_of_photos_2",
        "dpn_identifier": "12f9dc69-e753-435f-b1fd-1d6bc1229985",
        "dpn_size": 484362916,
        "node_1": "aptrust",
        "node_2": "hathi",
        "node_3": "sdr",  
        "dpn_created_at": "2014-11-24T18:56:11.348Z",
        "dpn_updated_at": "2014-11-24T19:17:03.715Z",
        "created_at": "2014-11-24T18:56:11.348Z",
        "updated_at": "2014-11-24T19:17:03.715Z", 
    }