Using the API
There are two APIs on the Audit Manager which can be used in order to retrieve information and update resources within ACE.
The early implementation of adding an API was done on top of the servlets (dubbed the Servlet API), which should be used with caution as the endpoints are not expected to be maintained moving forward.
There are also API endpoints under the /rest
path which offer a more REST-based approach
to accessing resources in ACE. This API is being maintained and updated to add more
functionality and be in line with more REST conventions. As ACE does not use semantic
versioning, this document should be checked for up to date models and responses from the
API when migrating versions.
Authentication
The ACE AM API uses Basic Auth
, which requires a username and password to be sent in the
Authorization
HTTP header. The user and password are delimited by a colon and are encoded
using base64
Example for the user ace with password secret-password
Authorization: Basic YWNlOnNlY3JldC1wYXNzd29yZA==
Responses
All APIs will typically return an HTTP 200 if an operation is successful. This is true for creating resources as well, which may be updated in the future.
It is also expected that resources returned are application/json
unless otherwise
specified.
Various json fields are returned as Strings on these interfaces instead of their
base representation. If you These include:
|
Errors
Error responses in the ACE AM API follow standard HTTP responses
HTTP 400
Bad Request: the client sent invalid data
HTTP 401
Unauthorized: A client is not authorized; the Authentication
header should be checked
HTTP 403
Forbidden: A client does not have permissions to use a resource;
the User Roles
for the should be checked
HTTP 404
Not Found: the requested resource does not exist
HTTP 409
Conflict: the requested resource already exists or is being used
HTTP 500
Internal ServerError: Check your /tmp/aceam.log
to see the issue with the server
(and report if necessary)
Servlet APIs
There are a few Servlets which can return json by appending ?json=true
as a query
parameter to the HTTP URL. They do not offer as much of an interface for selecting
specific data and tend to give as much as they can offer.
Status
Retrieve ALL status information about Collections being tracked by this Audit Manager
GET /Status?json=true
Response
{
"startup_complete": Boolean,
"paused": Boolean,
"collections": [
{
"id": Long
"name": String,
"group": String,
"directory": String,
"lastSync": Date as String,
"storage": String,
"checkPeriod": Integer as String,
"proxyData": Boolean as String,
"auditTokens": Boolean as String,
"state": String,
"totalFiles": Long,
"totalSize": Long,
"fileAuditRunning": Boolean,
"tokenAuditRunning": Boolean,
"totalErrors": Long,
"missingTokens": Long,
"missingFiles": Long,
"activeFiles": Long,
"corruptFiles": Long,
"invalidDigests": Long,
"remoteMissing": Long,
"remoteCorrupt": Long,
"fileAudit": {
"totalErrors": Long,
"newFilesFound": Long,
"filesSeen": Long,
"lastFileSeen": String,
"tokenAdded": Long
},
"tokenAudit": {
"totalErrors": Long,
"tokensSeen": Long,
"validTokens": Long
}
}]
}
Event Log
Retrieve EventLog information for a Collection/Collections
GET /EventLog?json=true
Query Parameters
Parameter | Type |
---|---|
collectionid |
Long |
logpath |
String |
sessionid |
Long |
View Summary
Retrieve Audit Summary reports for a Collection/Collections
GET /ViewSummary?json=true
Query Parameters
Parameter | Type |
---|---|
collectionid |
Long |
limit |
Integer |
Response
{
"collection": Long,
"summaries": [
{
"reportName": String,
"id": Long,
"collection": Long,
"collectionName": String,
"start": Date as String,
"end": Date as String,
"collectionState": {
String: Long
},
"logSummary": {
String: Long
}]
}
The collectionState and logSummary fields are populated by mapping keys to values
and as such don’t have field names which are well defined. In general the field name
will be some type of String, and its value will be a Long, and there can be multiple
fields in each of collectionState and logSummary .
|
List Item
For paths with large numbers of children, this can be a very slow operation |
GET /ListItem?collectionid={id}&json=true
Response
{
"parent": {
"id": Long,
"state": String,
"directory": Boolean,
"path": String,
"parentPath": String,
"lastSeen": Date as String,
"stateChange": Date as String,
"lastVisited": Date as String,
"size": Long
},
"children": [
{
"id": Long,
"state": String,
"directory": Boolean,
"path": String,
"parentPath": String,
"lastSeen": Date as String,
"stateChange": Date as String,
"lastVisited": Date as String,
"size": Long
}
]
}
REST API
The REST API for the Audit Manager is slowly being refined to follow standard access for resources. Endpoints which are at risk of being moved will be marked as such.
Collection Management
Add a Collection
Register a Collection into the Audit Manager for tracking
POST /rest/collection
Modify Collection
Modify the general settings for a collection
Only a few values are allowed to be updated: storage, directory, group, and settings (e.g. audit.period) |
POST /rest/collection/modify/{id}
List Operations
Get Collections By Group
Retrieve all Collections identified by their group. If no group is supplied, find Collections with no group.
GET /rest/collections/by-group/{group}
Response Body
[
{
"id": Long,
"name": String,
"directory": String,
"lastSync": Long,
"storage": String,
"state": String,
"group": String,
"digestAlgorithm": String,
"settings": {
"audit.period": Int as String,
"audit.tokens": Boolean as String,
"proxy.data": Boolean as String
},
"stateEnum": String
}
]
Get Collections
GET /rest/collections
Query Parameters
Parameter | Type | Values |
---|---|---|
group |
String |
* |
active |
Boolean |
true|false |
corrupt |
Boolean |
true|false |
Response Body
[
{
"id": Long,
"name": String,
"directory": String,
"lastSync": Long,
"storage": String,
"state": String,
"group": String,
"digestAlgorithm": String,
"settings": {
"audit.period": Int as String,
"audit.tokens": Boolean as String,
"proxy.data": Boolean as String
},
"stateEnum": String
}
]
Get Monitored Items
Retrieve all MonitoredItems for a Collection
GET /rest/collections/{id}/items
Query Parameters
Parameter | Type | Possible Values |
---|---|---|
state |
Character |
A (active) |
Irods Settings
Token Store Upload
Request Body
The request body must be a valid ACE Token Store. If it does not conform, a Bad Request will be returned.
SHA-256 ims.umiacs.umd.edu SHA-256 10058061 2018-12-14T16:34:50.000-05:00 291 /manifest-sha256.txt X:5a65ec57ffd76ba0276d3b1a4c54b8884662abc256c56bf1d73dbc5253a69a51 7ce27d4e3341c52ec0fb7f21dc124eb2f2b7153e210f9e8a7ae8a2a8b7135a9d:X X:5c150712032f825e3330e44b1dfbf3278fb89e0474d03877da39ce0932807d22 36b54a973fb43a37eac372ed1ae7ec8f1f34ef66d929f4a4fe7717026de2c656:X SHA-256 ims.umiacs.umd.edu SHA-256 10058061 2018-12-14T16:34:50.000-05:00 294 /tagmanifest-sha256.txt 5a665de34e494db0c8c3ebabf4ac01e8e7493abb3ab0789cd13b7bf18e9b5130:X 7ce27d4e3341c52ec0fb7f21dc124eb2f2b7153e210f9e8a7ae8a2a8b7135a9d:X X:5c150712032f825e3330e44b1dfbf3278fb89e0474d03877da39ce0932807d22 36b54a973fb43a37eac372ed1ae7ec8f1f34ef66d929f4a4fe7717026de2c656:X