OpenDCS Rest API is web application that provides access to the OpenDCS database using JSON (Java Script Object Notation). OpenDCS Rest API is intended to run as a stand-alone Java program. It uses embedded JETTY to implement the web services.
./opendcs-rest-api - contains source files for the OpenDCS REST API
./opendcs-rest-api-jetty - contains build scripts for generating a standalone Jetty installer for the OPENDCS REST API
./opendcs-web-client - contains source files for the OpenDCS Web Application Client
./opendcs-web-client-jetty - contains build scripts for generating a standalone Jetty installer for the web client
There are two types of installations/configurations. One is embedded Jetty bundles and the other is WAR files.
The gradle task ./gradlew :opendcs-rest-api:war
will create a war file in the build/libs
directory.
The SwaggerUI location can be found at the relative url path of /
The gradle task ./gradlew :opendcs-web-client:war
will create a war file in the build/libs
directory.
The Root URL for the service is specified using the command line arguments when the JETTY server is started. If the defaults are used, you can access the service from the local machine with: http://localhost:8080/odcsapi/function-call
For example, to get a list of platform references: http://localhost:8080/odcsapi/platformrefs
The gradle task ./gradlew :opendcs-rest-api-jetty:bundle
will create a tar ball in the build/distributions
directory.
This tar ball can be extracted and run with the start.sh
script.
The start.sh
script can be configured with the following arguments:
export DCSTOOL_HOME=/home/opendcs/OPENDCS
export DCSTOOL_USERDIR=/home/opendcs
export JAVA_OPTS="-DDCSTOOL_HOME=$DCSTOOL_HOME -DDCSTOOL_USERDIR=$DCSTOOL_USERDIR"
export JAVA_ARGS="-p 8081 -c odcsapi -cors /home/testuser/OPENDCS/opendcs_web_cors.cfg -s"
./start.sh
Access-Control-Allow-Origin:*
Access-Control-Allow-Headers:X-Requested-With,Content-Type,Accept,Origin,authorization
Access-Control-Allow-Methods:GET,POST,HEAD,OPTIONS,DELETE
Additionally, the build can run from a developer environment using the gradle task ./gradlew :opendcs-rest-api-jetty:startJetty
.
Properties read from gradle.properties will be used to configure the server.
The gradle task ./gradlew :opendcs-web-client-jetty:bundle
will create a tar ball in the build/distributions
directory.
This tar ball can be extracted and run with the start.sh
script.
The start.sh
script can be configured with the following arguments:
Additionally, the build can run from a developer environment using the gradle task ./gradlew :opendcs-web-client-jetty:startJetty
.
Properties read from gradle.properties will be used to configure the server.
The GitHub Action workflow default.yml contains the primary CI/CD pipeline for the project. This workflow is responsible for compiling, testing, analyzing, and packaging the project.
WAR and TAR files are generated as part of the CI/CD pipeline and are uploaded as artifacts in the GitHub Action.
During the analysis step of the CI/CD pipeline, the project is analyzed using SonarLint.
To view the analysis results, navigate to the project on the SonarCloud website. OpenDCS REST API SonarCloud
The gradle task ./gradlew sonar
will run a SonarLint analysis on the project.
The SonarLint analysis will be run against the SonarCloud server with an analysis uploaded to the OpenDCS REST API project.
The SonarCloud Quality Gate status for the Pull Request is reported in the Pull Request checks section for all PR's targeting the main branch.
The workflow default.yml includes the analysis step for GitHub Actions.
Jacoco code coverage scans are uploaded to SonarCloud. In order to reduce reporting redundancy, the Jacoco HTML reports are not available through the GitHub interface, but they can be generated locally through the gradle plugin.
The workflow owasp_zap.yml runs the OWASP Zap API scan to generate an HTML report detailing vulnerabilities in the OpenDCS REST API based on the OpenAPI documentation. OWASP Zap API scan documentation details the various options and rules for the scan. The OWASP Zap HTML report is attached to the GitHub Workflow run along with a shortened summary rendered in Markdown. At this time, the default configuration is used and the results are not used to gatekeep Pull Requests.
OpenDCS REST API targets JDK 8 compatibility for distribution. In order to ensure compatibility with future versions of Java, the GitHub workflow java_compatibility.yml will run a matrix build against the project to ensure compatibility with other JDK versions.
Artifact releases from this repository are found in the GitHub Releases page for the repository.
They can be created by using the GitHub interface. The GitHub workflow publish.yml will attach the WAR files and TAR files once the release is published.
A basic GitHub Codespaces configuration setup with a dev container with Java, Gradle, and SonarCloud integrations. Additionally, GitHub Copilot is available for users with appropriate licensing. The Codespaces are intended for the easy and consistent onboarding of developers who may not have access or experience with heavy-weight development IDE's.
Configuration for the dev container is found in devcontainer.json