Units of Measure Service

The Unit Service is a Maven multi-module project with each cloud implemention placed in its submodule.

This repository contains

1. 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, open pom.xml.
2. Tests are located in src/test/java/org/opengroup/osdu/unitservice/...
3. The openapi specification file is unit_service_openapi_v2.json.
4. 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

1. The project builds with maven. Make sure maven is installed locally.
2. 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:

Build and run the Docker container locally

1. Run the maven run command to have the .jar file generated.
2. Have the Azure subscription set up
3. Open a Powershell
4. Install the Azure CLI locally
5. Authenticate yourself to Azure Container Registry (acr) with the following command: az acr login --name delfi
6. Execute the following command to build the container image: docker build -t unit .
7. Execute the following command to build the container image: docker run -t --rm -p 8080:8080 unit
8. 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:

Release/deployment

VSTS release/deployment requires the following environment variables:

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