Endpoints in services to provide app with service version

Status

• Proposed
• [] Trialing
• [] Under review
• [] Approved
• [] Retired

Context

Initial set use cases were put together by @divido in osdu/platform/home#36 (closed)

Application Integration Support

It would be nice to have an ability for applications to know the version of services it is talking to. These versions should correspond to the Gitlab common code milestones. Such semantic versioning endpoint should be added to all services.

Use Cases

There are following possible use cases:

1. The end customer should have a way to query their environment to know what versions they are running. Then they would know that patches they see coming in on community have been applied to their environment.
2. Application developers would be able to query versions of the services they are working with to determine compatibility.
3. The CI pipeline can query the running instances of dependent services, and issue a warning if the major/minor doesn't match the currently executing one.
4. Response could have a commit hashcode, branch and repository name.
5. This endpoint also could be used for sanity checks.

Scope

Addition to an API for all OSDU services.

Decision

The git-commit-id-plugin provides commit information in out-of-the-box manner.

<plugin>
  <groupId>pl.project13.maven</groupId>
  <artifactId>git-commit-id-plugin</artifactId>
</plugin>

The spring-boot-maven-plugin provides version information in out-of-the-box manner.

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin<</artifactId>
</plugin>

A piece of custom code could be used to pull desired information from pom.xml from compiled resources.

Sample use

REST request

https://os-partition-jvmvia5dea-uc.a.run.app/api/partition/v1/info

and response

{
    "version": "0.10.0-SNAPSHOT",
    "artifactId": "partition-gcp",
    "name": "partition-gcp",
    "groupId": "org.opengroup.osdu",
    "buildTime": "2021-06-21T08:41:50.703Z"
    "branch": "gcp-entv2-stab"
    "commitId": "b2d47532ff4d275cdb208120fcbb0703383a88b2"
    "commitMessage": "MR 4711"
    "buildTime": "2021-06-21T08:41:50.703Z"
    "connectedOuterServices": { 
        "elasticSearch": {
             "version":"..."
        },
        "postgresSql": {
            "version":"..."
        },
        "opa": {
            "version":"..."
        }
    }
}

The value of version tag is the service version assigned in accordance with OSDU Versioning Strategy.

The node connectedOuterServices contains a dictionary with service-specific values.

Rationale

Consequences

Since this endpoint implementation will be added to all services, it will require careful planning and synchronization of effort across all development teams.

Some services are implemented using serverless approach (Azure Function Apps, AWS lambdas, GCP Cloud Functions, IBM Cloud Functions). There is no readily available solution to determining such services version. Consider deploying a separate function under basic URL to return version/build information:

# basic URL
https://os-partition-jvmvia5dea-uc.a.run.app/api/partition
# URL to return version information
https://os-partition-jvmvia5dea-uc.a.run.app/api/partition/info