JarCastingHygieia Audit API
Hygieia Audit API - Learn how to install and configure Hygieia audit APIs
Hygieia audit APIs are a collection of API endpoints that serve to audit CI/CD data gathered by Hygieia collectors. The audit API provides endpoints to audit individual widgets on the Dashboard. In addition to these endpoints, Hygieia also provides a dashboard-level audit API.
The audit API logic adds various audit flags depending on the data.
For detailed information on audit APIs, see the Swagger documentation available at http://[your-domain].com/apiaudit/swagger/index.html#.
Hygieia uses Spring Boot to package the APIs as an executable JAR file with dependencies.
Table of Contents
Setup Instructions
To configure the Hygieia Audit API layer, execute the following steps:
-
Step 1 - Artifact Preparation:
Please review the two options in Step 1 to find the best fit for you.
Option 1 - Download the artifact:
You can download the SNAPSHOTs from the SNAPSHOT directory here or from the maven central repository here.
Option 2 - Build locally:
To configure the Hygieia API Audit layer, git clone the api audit repo. Then, execute the following steps:
To package the Audit API source code into an executable JAR file, run the maven build from the
\api-auditdirectory of your source code installation:mvn install
The output file
apiaudit.jaris generated in the\api-audit\targetfolder.Once you have chosen an option in Step 1, please proceed:
-
Step 2: Set Parameters in the API Properties File
Set the configurable parameters in the
dashboard.propertiesfile to connect to the Dashboard MongoDB database instance, including properties required by the audit API module. To configure the parameters, refer to the API Audit properties section.For more information about the server configuration, see the Spring Boot documentation.
-
Step 3: Run the API
To run the executable file, change directory to 'api-audit\target' and then execute the following command from the command prompt:
java -jar apiaudit.jar --spring.config.location=C:\[path to]\api-audit.properties
Verify API access from the web browser using the url: http://localhost:8080/apiaudit/ping.
By default, the server starts at port
8080and uses the context path/api-audit. You can configure these values in theapi-audit.propertiesfile for the following properties:server.contextPath=/api-audit server.port=8080
Note: The 'jasypt.encryptor.password' system property is used to decrypt the database password.
API Audit Properties
The sample api-audit.properties lists parameters with sample values to configure the audit API layer. Set the parameters based on your environment setup.
# api-audit.properties
dbname=dashboarddb
dbusername=dashboarduser[MogoDb Database Username, defaults to empty]
dbpassword=dbpassword[MongoDB Database Password, defaults to empty]
dbhost=[Host on which MongoDB is running, defaults to localhost]
dbport=[Port on which MongoDB is listening, defaults to 27017]
dbreplicaset=[False if you are not using MongoDB replicaset]
dbhostport=[host1:port1,host2:port2,host3:port3]
server.contextPath=[Web Context path, if any]
server.port=[Web server port - default is 8080]
logRequest=false
logSplunkRequest=false
serviceAccountOU=SAOU1,SAOU2 [comma separated list of OU setup in LDAP for whitelist of Service Accounts]
# pattern to match the featureID/storyNumber (Jira ID, VersionOne ID, etc) for traceability
featureIDPattern=((?<!([A-Za-z]{1,10})-?)[A-Z]+-\\d+)
All values in the api-audit.properties file are optional. If you have MongoDB installed with no authorization, you must be able to run the API even without the properties file.
Note: If the value of dbusername is empty, then system skips MongoDB authorization.
Docker Image for API Audit
You can install Hygieia by using a docker image from docker hub. This section gives detailed instructions on how to download and run with Docker.
-
Step 1: Download
Navigate to the audit api docker hub location here and download the latest image (most recent version is preferred). Tags can also be used, if needed.
-
Step 2: Run with Docker
Docker run -e SKIP_PROPERTIES_BUILDER=true -v properties_location:/hygieia/config image_name-e SKIP_PROPERTIES_BUILDER=true
indicates whether you want to supply a properties file for the java application. If false/omitted, the script will build a properties file with default values-v properties_location:/hygieia/config
if you want to use your own properties file that located outside of docker container, supply the path here.- Example:
-v /Home/User/Document/application.properties:/hygieia/config
- Example:
Create a New Audit API
The steps to create a new audit API are as follows:
- Create a new rest controller or add to an existing controller.
- Create a new service interface and new service implementation.
- Add new request and response classes.
Note: For common data models used in the audit APIs, refer the core module's model package.
