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-web-client - contains source files for the OpenDCS Web Application Client ./opendcs-integration-test - contains scripts for running embedded tomcat to deploy the REST API and Web Client wars for testing.
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 //swaggerui. Assuming the context is 'odcsapi', an example of the SwaggerUI location is http://localhost:8080/odcsapi/swaggerui. These files are being served up from the resource file 'SwaggerResources.java' file located at 'src/main/java/org/opendcs/odcsapi/res/SwaggerResources.java'.
The bundled web.xml contains the following properties that should be configured for your system.
opendcs.rest.api.authorization.type- supports a comma separated list of authorization types. These can include basic,sso,openid. See section on authorization for details.opendcs.rest.api.authorization.expiration.duration- denotes the duration that an authorization attempt is valid for. Defaults to 15 minutes.opendcs.rest.api.cwms.office- office id specific to CWMS systems. This is the office the authorizing user will check privileges for.opendcs.rest.api.authorization.jwt.jwkset.url- for openid authorization this is the JWK Set URLopendcs.rest.api.authorization.jwt.issuer.url- for openid authorization this is the Issuer URL
The gradle task ./gradlew :opendcs-web-client:war will create a war file in the build/libs directory.
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
The OpenDCS REST API supports three authorization mechanisms Basic Authentication, Container Single Sign-On, and OpenID Connect.
When the client attempts to access endpoints that are not marked with the Guest role the authorization mechanisms are checked to determine which roles are currently granted to the client. See ./opendcs-rest-api/README.md for more info.