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:

category: the status level of severity, one of 'error', 'warn', 'info', or 'debug'
service: name of the originating service, e.g. 'DataPackageManager-1.0'

Other optional elements are of the following:

oid: an object identifier value for the audit log entry, as generated and assigned by the Audit Manager when the audit log entry is created, e.g. '477'.
entryTime: the date and time of the audit log entry, in ISO8601 format, e.g. '2015-01-26 15:06:02.515'. An entryTime timestamp value is automatically generated by the Audit Manager when a new audit log entry is created.
serviceMethod: the originating service method pertaining to the creation of the audit log entry, e.g. 'readDataEntity'
responseStatus: the HTTP response status code from the service method, e.g. '200'
resourceId: the resource ID related to audit log entry, if applicable, e.g. 'https://pasta.lternet.edu/package/metadata/eml/knb-lter-nwk/1416/1'
user: the user distinguished name on whose behalf the service method was executed, e.g. 'uid=ucarroll,o=LTER,dc=ecoinformatics,dc=org'
userAgent: the userAgent value of the request
groups: a comma-separated list of groups that the user is a member of, e.g. 'authenticated'
authSystem: the authentication system, e.g. 'https://pasta.edirepository.org/authentication'
entryText: auxiliary information to accompany the audit log entry

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 URL	Brief description
POST	Create 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 : report	Get Audit Report operation, gets a list of zero or more audit records matching the query parameters as specified in the request.
GET : csvreport	Get Audit CSVReport operation, gets a list of zero or more audit records matching the query parameters as specified in the request and streams back a comma separated values result set.
GET : count	Get Audit Count operation, returns the count of audit log records from the audit table (named "eventlog") matching the provided criteria.
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.
GET : reads/{scope}/{identifier}	Get DocId Reads operation, returns an XML-formatted list that summarizes all the successful reads (total reads and non-robot reads) for all the resources of a given PASTA document ID, where a document ID is of the format "scope.
GET : reads/{scope}/{identifier}/{revision}	Get PackageId Reads operation, returns an XML-formatted list that summarizes all the successful reads (total reads and non-robot reads) for all the resources of a given PASTA package ID, where a package ID is of the format "scope.

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>
       <userAgent>userAgent field of the web service request</userAgent>
       <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>
           <userAgent>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36</userAgent>
           <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.

Requests:

Message Body	MIME type	Sample Request
None		`curl -i -X GET "https://pasta.lternet.edu/audit/report/3`

Responses:

If the request is successful, the response will contain xml.

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`
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 : csvreport

Get Audit CSVReport operation, gets a list of zero or more audit records matching the query parameters as specified in the request and streams back a comma separated values result set.

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

Responses:

If the request is successful, the response will contain applications/csv text.

Status	Reason	Entity	MIME type
200 OK	If the request was successful.	The specified query's result set in CSV format.	`text/csv`
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 the count of 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".

Requests:

Message Body	MIME type	Sample Request
None		`curl -i -X GET "https://pasta.lternet.edu/audit/count?resourceId=https://pasta.lternet.edu/package/eml/edi/12/1"`

Responses:

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

Status	Reason	Entity	MIME type
200 OK	If the request was successful.	The count. For example, "10."	`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`

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`

GET : reads/{scope}/{identifier}

Get DocId Reads operation, returns an XML-formatted list that summarizes all the successful reads (total reads and non-robot reads) for all the resources of a given PASTA document ID, where a document ID is of the format "scope.identifier" (excludes revision). Note: as of 23 November 2022, robot-based events are no longer recorded. For this reason, total reads and non-robot reads will increase at the same rate.

Responses:

Status	Reason	Entity	MIME type
200 OK	If the request was successful.	The XML-formatted list of resource reads for the specified scope and identifier.	`application/xml`
400 Bad Request	If the specified identifier number cannot be parsed as an integer.	An error message.	`text/plain`
401 Unauthorized	If the requesting user is not authorized to retrieve this information.	An error message.	`text/plain`

If the request is successful, the response will contain XML text. For example, when scope is "edi" and identifier is "0", the XML returned might look as follows:

   <?xml version="1.0" encoding="UTF-8"?>
   <resourceReads>
     <resource>
       <resourceId>https://pasta-d.lternet.edu/package/eml/edi/0/0</resourceId>
       <resourceType>dataPackage</resourceType>
       <scope>edi</scope>
       <identifier>0</identifier>
       <revision>0</revision>
       <totalReads>29</totalReads>
       <nonRobotReads>22</nonRobotReads>
     </resource>
     <resource>
        <resourceId>https://pasta-d.lternet.edu/package/metadata/eml/edi/0/0</resourceId>
        <resourceType>metadata</resourceType>
        <scope>edi</scope>
        <identifier>0</identifier>
        <revision>0</revision>
        <totalReads>41</totalReads>
        <nonRobotReads>34</nonRobotReads>
     </resource>
     <resource>
        <resourceId>https://pasta-d.lternet.edu/package/report/eml/edi/0/0</resourceId>
        <resourceType>report</resourceType>
        <scope>edi</scope>
        <identifier>0</identifier>
        <revision>0</revision>
        <totalReads>1</totalReads>
        <nonRobotReads>1</nonRobotReads>
     </resource>
     <resource>
        <resourceId>https://pasta-d.lternet.edu/package/report/eml/edi/0/1</resourceId>
        <resourceType>report</resourceType>
        <scope>edi</scope>
        <identifier>0</identifier>
        <revision>1</revision>
        <totalReads>1</totalReads>
        <nonRobotReads>1</nonRobotReads>
     </resource>
     <resource>
        <resourceId>https://pasta-d.lternet.edu/package/eml/edi/0/1</resourceId>
        <resourceType>dataPackage</resourceType>
        <scope>edi</scope>
        <identifier>0</identifier>
        <revision>1</revision>
        <totalReads>7</totalReads>
        <nonRobotReads>7</nonRobotReads>
     </resource>
   </resourceReads>

GET : reads/{scope}/{identifier}/{revision}

Get PackageId Reads operation, returns an XML-formatted list that summarizes all the successful reads (total reads and non-robot reads) for all the resources of a given PASTA package ID, where a package ID is of the format "scope.identifier.revision". Note: as of 23 November 2022, robot-based events are no longer recorded. For this reason, total reads and non-robot reads will increase at the same rate.

Responses:

Status	Reason	Entity	MIME type
200 OK	If the request was successful.	The XML-formatted list of resource reads for the specified scope, identifier, and revision.	`application/xml`
400 Bad Request	If the specified identifier or revision value cannot be parsed as an integer.	An error message.	`text/plain`
401 Unauthorized	If the requesting user is not authorized to retrieve this information.	An error message.	`text/plain`

If the request is successful, the response will contain XML text. For example, when scope is "edi" and identifier is "0" and revision is "0", the XML returned might look as follows:

   <?xml version="1.0" encoding="UTF-8"?>
   <resourceReads>
     <resource>
       <resourceId>https://pasta-d.lternet.edu/package/eml/edi/0/0</resourceId>
       <resourceType>dataPackage</resourceType>
       <scope>edi</scope>
       <identifier>0</identifier>
       <revision>0</revision>
       <totalReads>29</totalReads>
       <nonRobotReads>22</nonRobotReads>
     </resource>
     <resource>
        <resourceId>https://pasta-d.lternet.edu/package/metadata/eml/edi/0/0</resourceId>
        <resourceType>metadata</resourceType>
        <scope>edi</scope>
        <identifier>0</identifier>
        <revision>0</revision>
        <totalReads>41</totalReads>
        <nonRobotReads>34</nonRobotReads>
     </resource>
     <resource>
        <resourceId>https://pasta-d.lternet.edu/package/report/eml/edi/0/0</resourceId>
        <resourceType>report</resourceType>
        <scope>edi</scope>
        <identifier>0</identifier>
        <revision>0</revision>
        <totalReads>1</totalReads>
        <nonRobotReads>1</nonRobotReads>
     </resource>
   </resourceReads>

Audit Manager web service API

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

Request Summary

Request Detail

Request entity:

Responses:

Requests:

Responses:

Query Parameters:

Responses:

Query Parameters:

Responses:

Query Parameters:

Requests:

Responses:

Query Parameters:

Responses:

Responses:

Responses: