Merge pull request #507 from nasa/harmony-1580

HARMONY-1580: Document the versions endpoint
nasa · Nov 28, 2023 · 886865d · 886865d
2 parents b352ae0 + a2e9c24
commit 886865d
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 13 deletions.
diff --git a/services/harmony/app/markdown/docs.md b/services/harmony/app/markdown/docs.md
@@ -16,4 +16,6 @@
 
 !!!include(stac.md)!!!
 
-!!!include(cloud-access.md)!!!
+!!!include(cloud-access.md)!!!
+
+!!!include(versions.md)!!!
diff --git a/services/harmony/app/markdown/endpoints.md b/services/harmony/app/markdown/endpoints.md
@@ -2,18 +2,18 @@
 
 All of the public endpoints for Harmony users other than the OGC Coverages and WMS APIs are listed in the following table. The Coverages and WMS APIs are described in the [Using the Service APIs section](#using-the-service-apis).
 
-| route                  | description                                                                               |
-|------------------------|-------------------------------------------------------------------------------------------|
-| /                      | The Harmony landing page                                                                  |
-| /capabilities          | [Get harmony capabilities for the provided collection](#capabilities-details)             |
-| /cloud-access          | [Generates AWS credentials for accessing processed data in S3](#cloud-access-details)     |
-| /docs                  | These documentation pages                                                                 |
-| /docs/api              | The Swagger documentation for the OGC Coverages API                                       |
-| /jobs                  | [The jobs API for getting job status, pausing/continuing/canceling jobs](#jobs-details)   |
-| /stac                  | [The API for retrieving STAC catalog and catalog items for processed data](#stac-details) |
-| /staging-bucket-policy | The policy generator for external (user) bucket storage                                   |
-| /versions              | Returns JSON indicating what version (image tag) each deployed service is running         |
-| /workflow-ui           | The Workflow UI for monitoring and interacting with running jobs                          |
+| route                  | description                                                                                     |
+|------------------------|-------------------------------------------------------------------------------------------------|
+| /                      | The Harmony landing page                                                                        |
+| /capabilities          | [Get harmony capabilities for the provided collection](#capabilities-details)                   |
+| /cloud-access          | [Generates AWS credentials for accessing processed data in S3](#cloud-access-details)           |
+| /docs                  | These documentation pages                                                                       |
+| /docs/api              | The Swagger documentation for the OGC Coverages API                                             |
+| /jobs                  | [The jobs API for getting job status, pausing/continuing/canceling jobs](#jobs-details)         |
+| /stac                  | [The API for retrieving STAC catalog and catalog items for processed data](#stac-details)       |
+| /staging-bucket-policy | The policy generator for external (user) bucket storage                                         |
+| /versions              | [Returns JSON indicating the image and tag each deployed service is running](#versions-details) |
+| /workflow-ui           | The Workflow UI for monitoring and interacting with running jobs                                |
 ---
 **Table {{tableCounter}}** - Harmony routes other than OGC Coverages and WMS
 

diff --git a/services/harmony/app/markdown/versions.md b/services/harmony/app/markdown/versions.md
@@ -0,0 +1,30 @@
+### <a name="versions-details"></a> Getting the versions of images used in each of the Harmony backend service chains
+
+Using the `versions` endpoint, a user can get a list of all of the docker images and versions used in harmony backend service chains. Service providers use this endpoint to verify the versions of their services deployed to an environment.
+
+#### Get backend service version information
+
+```
+
+{{root}}/versions
+
+```
+**Example {{exampleCounter}}** - Getting backend service versions using the `versions` API
+
+The returned JSON response is an array of service version information with the following fields:
+
+| field | description                                                                                                                       |
+|-------|-----------------------------------------------------------------------------------------------------------------------------------|
+| name | The name of the backend service chain as defined in [services.yml](https://github.com/nasa/harmony/blob/main/config/services.yml). |
+| images | An array of the images used in the service chain.                                                                                |
+
+Each image has the following fields:
+| field | description                                                        |
+|-------|--------------------------------------------------------------------|
+| image | The name of the docker image.                                      |
+| tag | The docker image tag.                                                |
+| lastUpdated | (optional) The time the image was last updated if available. |
+| imageDigest | (optional) The image digest if available.                    |
+
+---
+**Table {{tableCounter}}** - Harmony versions response fields