Units of Measure Service
The Unit Service is a Maven multi-module project with each cloud implemention placed in its submodule.
This repository contains
- The Java implementation of the Units of Measure catalog and conversion service (aka dps-unit-service). The Java code is located in the
src
folder. To open the Java project, openpom.xml
. - Tests are located in
src/test/java/org/opengroup/osdu/unitservice/...
- The openapi specification file is
unit_service_openapi_v2.json
. - Python integration and health tests in the
testing
folder. See also the test's README.md
Note on API Versions
The Unit Service supports 2 APIs. These APIs are V2 and V3. Note: The V2 API is depcrecated
The V2 and V3 APIs have the same functionality, however the V3 API uses query params vs inline route path params to set variables. This allows for better handling of special characters and support for future extensibility of the Unit Service's routes.
Both APIs are available in Swagger at https://[Unit_Service_Host]/api/unit/swagger-ui.html
Prerequisites
- The project builds with maven. Make sure maven is installed locally.
- The project requires the Lombok plug-in installed for your IDE.
Build service and run unit tests
mvn clean install
Running Unit Service locally
Azure
Build and run Unit Service locally using bash
- Set the required environments described in Build and Release/deployment sections
- Navigate to the Unit Service's root folder
unit-service
- Build core and run unit tests in command line:
mvn clean install # To run without tests add -Dmaven.test.skip=true
- Navigate to the Unit Service's root folder
unit-service
- Run application with command
java -jar provider/unit-azure/unit-aks/target/unit-aks-1.0.0.jar
Running Azure Unit Service using IntelliJ IDEA
Navigate to the Create Run/Debug Configuration tool Select 'Add New Configuration' and select Application
Type the next commands into the suggested fields:
- Working directory:
{path_to_the_unit}/unit-service
- Main class:
org.opengroup.osdu.unitservice.UomAksApplication
- Use classpath of module:
unit-aks
Note: If you don't see "unit-aks" in the dropdown menu - find appropriate pom.xml and click "Add as a Maven project" - Environment variables: Set the required environments described in Build and Release/deployment section
Execute Run or Debug for configured Application
Debug locally - e.g. using Postman
In the Postman Settings / General, turn SSL certificate validation off when running locally.
Similarly, when not using Postman but client code, set the configuration verify_ssl
false (see instructions)
Run application using debug mode and use Postman to send a GET request to obtaining the Swagger API documentation:
http://localhost:8080/api/unit/v2/api-docs
or send a POST request to the service:
http://localhost:8080/api/unit/v2/...
Open the Swagger-UI:
http://localhost:8080/api/unit/swagger-ui.html
Headers for Postman:
Key | Value |
---|---|
Authorization | Bearer <token>
|
data-partition-id | $MY_TENANT (see testing\README.md) |
Build and run the Docker container locally
- Run the
maven run
command to have the .jar file generated. - Have the Azure subscription set up
- Open a Powershell
- Install the Azure CLI locally
- Authenticate yourself to Azure Container Registry (acr) with the following command:
az acr login --name delfi
- Execute the following command to build the container image:
docker build -t unit .
- Execute the following command to build the container image:
docker run -t --rm -p 8080:8080 unit
- Use Postman or curl to try out the endpoints
Build
Azure
VSTS build definition is located at build definitions/dps/unit-service, which requires the following environment variables:
Variable | Contents |
---|---|
UNIT_CATALOG_FILENAME | Required, file name for the unit catalog to use. Default to /mnt/unit_catalogs/unit_catalog_v2.json |
GCP
Instructions for build the GCP unit-service can be found here
Release/deployment
VSTS release/deployment requires the following environment variables:
Variable | Contents |
---|---|
ENTITLEMENT_URL | Required |
GCP
Instructions for deployment the GCP unit-service to App Engine can be found here
Instructions for deployment the GCP unit-service to GKE can be found here