Audit Manager web service API


Base URL - https://audit.lternet.edu/audit


The Audit Manager web service allows services to create, and users to read PASTA audit records (also known as "audit log entries").

An auditRecord XML element will always consist of these required sub-elements:

Other optional elements are of the following:

Note that 'oid' and 'entryTime' values are automatically generated by the Audit Manager when new audit entries are created. Thus, although they are technically optional elements, they will always be present in audit records that are read from PASTA.



Request Summary

HTTP Verb : Relative URLBrief description
POSTCreate Audit Record operation, creates a new logged entry in the Audit Manager's logging database.
GET : report/{oid}Get Audit Record operation, retrieves a single audit record based on the audit identifier value specified in the path.
GET : reportGet Audit Report operation, gets a list of zero or more audit records matching the query parameters as specified in the request.
GET : countGet Audit Count operation, returns a count of the number audit log records from the audit table (named "eventlog") matching the provided criteria.
GET : recent-uploadsGet Recent Uploads operation, gets a list of zero or more audit records of either recently inserted or recently updated data packages, as specified in the request.



Request Detail


POST

Create Audit Record operation, creates a new logged entry in the Audit Manager's logging database.

Request entity:

The request entity should be an XML document (MIME type application/xml) that is described below.

   <auditRecord>
       <category>error|warn|info|debug</category>
       <service>service</service>
       <serviceMethod>service method</serviceMethod>
       <responseStatus>HTTP response status code</responseStatus>
       <resourceId>resource identifier</resourceId>
       <user>user distinguished name</user>
       <groups>groups list</groups>
       <authSystem>authentication system</authSystem>
       <entryTextt>auxiliary info text</entryText>
   </auditRecord>
 

The category and service elements are mandatory.

Example auditRecord XML document:
       <auditRecord>
           <category>warn</category>
           <service>DataPackageManager-1.0</service>
           <serviceMethod>listDataEntities</serviceMethod>
           <responseStatus>404</responseStatus>
           <resourceId></resourceId>
           <user>uid=ucarroll,o=LTER,dc=ecoinformatics,dc=org</user>
           <groups>authenticated</groups>
           <authSystem>https://pasta.edirepository.org/authentication</authSystem>
           <entryText>No entity resources found for scope abc</entryText>
       </auditRecord>
 

Responses:

Status Reason Entity MIME type
201 Created If the request to create an audit entry was successful. None, but the Location header will contain a URL that references the new subscription. N/A
400 Bad Request If the request entity contains an error, such as improperly formatted XML. An error message. text/plain
401 Unauthorized If the requesting user is not authorized to create log entries. An error message. text/plain
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request. For example, a SQL error occurred, or an unexpected condition was encountered. An error message text/plain


GET : report/{oid}

Get Audit Record operation, retrieves a single audit record based on the audit identifier value specified in the path.

Responses:

If the request is successful, the response will contain plain text.

Status Reason Entity MIME type
200 OK If the request was successful. The specified subscription's attributes. text/plain
400 Bad Request If the specified identification number cannot be parsed as an integer. An error message. text/plain
401 Unauthorized If the requesting user is not authorized to read the specified subscription. An error message. text/plain
404 Not Found If the requested log entry does not exist. An error message. text/plain


GET : report

Get Audit Report operation, gets a list of zero or more audit records matching the query parameters as specified in the request.

Query Parameters:

Parameter Value Constraints
category debug, info, error, warn
service Any of the PASTA services.
serviceMethod Any of the PASTA service Resource class JAX-RS methods.
user Any user.
group Any group.
authSystem A valid auth system identifier.
status A valid HTTP Response Code.
resourceId A PASTA resource identifier, e.g. https://pasta.lternet.edu/package/eml/knb-lter-and/2719/6, or a substring thereof (see below)
fromTime An ISO8601 timestamp
toTime An ISO8601 timestamp
limit A positive whole number

The query parameters fromTime and optionally toTime should be used to indicate a time span. When toTime is absent, the report will consist of all matching records up to the current time. Either of these parameters may only be used once.
The query parameter limit sets an upper limit on the number of audit records returned. For example, "limit=1000".
The query parameter resourceId will match any audit log entry whose resourceId value contains the specified string value. Thus, a query parameter of "resourceId=knb-lter-and" will match any audit log entry whose resourceId value contains the substring "knb-lter-and", while a query parameter of "resourceId=knb-lter-and/2719/6" will match any audit log entry whose resourceId value contains the substring "knb-lter-and/2719/6".

Responses:

If the request is successful, the response will contain XML text.

Status Reason Entity MIME type
200 OK If the request was successful. The specified subscription's attributes. application/xml
400 Bad Request If the specified identification number cannot be parsed as an integer. An error message. text/plain
401 Unauthorized If the requesting user is not authorized to read the specified subscription. An error message. text/plain


GET : count

Get Audit Count operation, returns a count of the number audit log records from the audit table (named "eventlog") matching the provided criteria.

Query Parameters:

Parameter Value Constraints
category debug, info, error, warn
service Any of the PASTA services.
serviceMethod Any of the PASTA service Resource class JAX-RS methods.
user Any user.
group Any group.
authSystem A valid auth system identifier.
status A valid HTTP Response Code.
resourceId A PASTA resource identifier, e.g. https://pasta.lternet.edu/package/eml/knb-lter-and/2719/6, or a substring thereof (see below)
fromTime An ISO8601 timestamp
toTime An ISO8601 timestamp
limit A positive whole number

The query parameters fromTime and optionally toTime should be used to indicate a time span. When toTime is absent, the count will include of all matching records up to the current time. Either of these parameters may only be used once.
The query parameter limit sets an upper limit on the number of audit records returned. For example, "limit=1000".
The query parameter resourceId will match any audit log entry whose resourceId value contains the specified string value. Thus, a query parameter of "resourceId=knb-lter-and" will match any audit log entry whose resourceId value contains the substring "knb-lter-and", while a query parameter of "resourceId=knb-lter-and/2719/6" will match any audit log entry whose resourceId value contains the substring "knb-lter-and/2719/6".

Responses:

If the request is successful, the response will contain XML text.

Status Reason Entity MIME type
200 OK If the request was successful. The specified subscription's attributes. application/xml
400 Bad Request If the specified identification number cannot be parsed as an integer. An error message. text/plain
401 Unauthorized If the requesting user is not authorized to read the specified subscription. An error message. text/plain


GET : recent-uploads

Get Recent Uploads operation, gets a list of zero or more audit records of either recently inserted or recently updated data packages, as specified in the request.

Query Parameters:

Parameter Value Constraints
serviceMethod Either of "createDataPackage" or "updateDataPackage"
fromTime An ISO8601 timestamp
limit A positive whole number

The query parameter serviceMethod should have the value "createDataPackage" (to retrieve recent inserts) or "updateDataPackage" (to retrieve recent updates)
The query parameter fromTime is used to specify the date/time in the past that represents the oldest audit records that should be returned. Data packages uploaded prior to that time are not considered recent uploads and are thus filtered from the query results.
The query parameter limit sets an upper limit on the number of audit records returned. For example, "limit=3".

Responses:

If the request is successful, the response will contain XML text.

Status Reason Entity MIME type
200 OK If the request was successful. The specified subscription's attributes. application/xml
400 Bad Request If the specified identification number cannot be parsed as an integer. An error message. text/plain
401 Unauthorized If the requesting user is not authorized to read the specified subscription. An error message. text/plain