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 as String on a data type, it means the base data type will be serialized as a String.

These include:

  • Date

  • Integer

  • Boolean

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

Response

{
    "start": Int
    "count": Int,
    "session": Long,
    "path": Long
    "collection": Long,
    "filter": [],
    "events": [
        {
            "id": Long,
            "date": Date as String,
            "session": Long,
            "type": Int,
            "description": String,
            "collection": Long,
            "path": String
        }
    ]
}

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.

Report

Retrieve the current Report about a Collection.

GET /Report?collectionid={id}&json=true

Response

{
    "collection": Long,
    "count": Long,
    "next": Long,
    "entries": [
        {
            "id": Long,
            "state": String,
            "directory": String,
            "path": String,
            "pathParent": String,
            "lastSeen": Date as String,
            "stateChange": Date as String,
            "lastVisited": Date as String,
            "fileDigest": String
        }
    ]
}

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

Request Body
{
    "name": String,
    "group": String,
    "directory": String,
    "storage": String,
    "settings": {
        "audit.period": Integer as String,
        "audit.tokens": Boolean as String,
        "proxy.enabled": Boolean as String
    }
    "digestAlgorithm": String
}
Response Body
{
    "id": Long
}

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}

Request Body
{
    "group": String,
    "directory": String,
    "storage": String,
    "settings": {
        "audit.period": Integer as String,
        "audit.tokens": Boolean as String,
        "proxy.enabled": Boolean as String
    }
}
Response

On a successful update an HTTP 200 is returned

Get Collection

Retrieve a Collection in the Audit Manager. As there are multiple ways of identifying a Collection, 3 endpoints are given in order to query.

GET /rest/collection/settings/by-id/{id}
GET /rest/collection/settings/by-name/{name}
GET /rest/collection/settings/by-name/{name}/{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
}

Audit a Collection

Initiate a file audit for a given Collection. If specified, audit only the corrupt MonitoredItems.

POST /rest/collection/audit/{id}

Query Parameters

Parameter Type Values

corrupt

Boolean

true|false

Response

On a successful audit trigger an HTTP 200 is returned

Compare Items

Compare to Manifest

Compare the Monitored Items of a Collection to a json manifest of items

POST /rest/compare/{id}

Request Body
[{
    "path": String,
    "digest": String
}]
Response Body
{
    "diff": [String],
    "match": [String],
    "notFound": [String]
}

List Operations

Get Groups

Get the groups which are registered in the Audit Manager

GET /rest/groups

Response Body

The response body is a json array populated with the String value of the group names

[String]

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)
C (corrupt)
M (local file missing)
T (no token)
I (invalid token)
P (peer file missing)
D (peer digest different)
R (registered; not audited)

Response Body

A json list populated by the MonitoredItems

[
    {
        "id": Long,
        "path": String,
        "state": String,
        "fileDigest": String,
        "size": Long,
        "lastSeen": Long,
        "stateChange": Long,
        "lastVisited": Long
    }
]

Irods Settings

Get Irods Settings

Get the current iRods settings associated with a collection

GET /rest/settings/irods/{collectionId}

Response Body
{
    "id": Long,
    "username": String,
    "password": String,
    "zone": String,
    "server": String,
    "port": Integer
}

Update Irods Settings

Create or Update iRods settings for a collection

POST /rest/settings/irods/{collectionId}

Request Body
{
    "username": String,
    "password": String,
    "zone": String,
    "server": String,
    "port": Integer
}

Token Store Upload

Upload

Upload a TokenStore for a given collection id

POST /rest/tokenstore/{id}

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
Response

HTTP 200: The token store was accepted and is being processed