API Gateway

To support examination and testing of APIs implemented for particular domains and in various programming languages, VRO offers an API Gateway that provides a Swagger UI for manual exploration of APIs offered by VRO.

Refer to PR #1591 and PR #1578 for details.

To expose APIs for each domain, an API Gateway offers a Swagger UI to inspect API offerings.

• In a local (docker-compose) environment, it is available at http://localhost:8060/.
• In the Dev (LHDI) environment, it is available at https://dev.lighthouse.va.gov/abd-vro/. It's also available in other LHDI Development Environments.

When the user selects a "Destination" in the Swagger UI, the API Gateway queries domain-specific containers to retrieve the OpenAPI spec and presents them in a Swagger UI.

Adding a new domain API for LHDI deployments and Swagger UI

Pre-requisite: a domain container serves up an OpenAPI spec on some exposed port in LHDI

First, update Helm configurations to route domain URLs to the desired domain container:

• In the VirtualService, add a URL rewrite, route destination, and header X-Forwarded-Prefix configuration
  • The URL rewrite makes the URL compatible with the route destination in the domain container.
  • The X-Forwarded-Prefix header is needed to prepend the prefix to URLs generated by the domain container.
• Deploy to LHDI and test to make sure the URL rewrite and X-Forwarded-Prefix works.
  • In particular, ensure that the URL to the domain's OpenAPI spec works.

Then, update Swagger UI of the API Gateway:

• Add an entry with the URL to the domain's OpenAPI spec to api-gateways application.yml
• Test the API Gateway locally (see section below) and update application-local.yml with URL rewrite configuration for the new domain container.
• Deploy to LHDI and test VRO's Swagger UI. For the dev LHDI env, go to https://dev.lighthouse.va.gov/abd-vro.

Testing the API Gateway locally

• Run the API Gateway: ENV=local ./gradlew :api-gateway:bootRun
  • ENV=local causes api-gateway/src/main/resources/application-local.yml to be loaded. In this file, the spring.cloud.gateway.routes configurations cause URLs to be rewritten, similar to the VirtualService settings in the Helm configuration.
  • Alternatively, to use the api-gateway defined in docker-compose.yml, run docker compose up -d api-gateway.
• Run the domain APIs:

# Start VRO's App API
./gradlew :app:dockerComposeUp
# This API's Swagger UI is available at http://localhost:8080/swagger

# Optionally start a domain API, such as Team CC's API -- see domain-cc/README.md

• Browse to http://localhost:8060/, read instructions, and click Swagger UI
  • Note the definition "0. Gateway API" is selected and its basic API is shown. Expand the GET /hello endpoint and click "Try it out", then "Execute". The response should be a code 200 with body Hi!.
  • Select the definition "App API". To "Try it out", make sure to select the "/vro-app" server on the left dropdown. Selecting this server will cause requests to go to http://localhost:8060/vro-app/<endpoint>, which will get re-written as specified in application-local.yml (i.e., requests will be rerouted to the vro-app container at http://localhost:8110/<endpoint> by default).

Implementation Details

• It queries URLs specified by springdoc.swagger-ui.urls. The same URLs are routed differently depending on the environment:
  • In the local environment, the URLs are rerouted using spring.cloud.gateway.routes
  • In the LHDI environments, the URLs are rerouted using Istio's VirtualService in Helm
  • To have the Swagger UI offer the correct URL prefix to access the API endpoints, the server URL environment variable is set in Helm configurations.
• The source API can be accessed directly (without going through the API Gateway). For example, to access the VRO App API:
  • In the local environment, http://localhost:8110/swagger-ui/index.html and http://localhost:8110/v3/api-docs
  • In the Dev (LHDI) environments, https://dev.lighthouse.va.gov/vro-app/swagger-ui/index.html and https://dev.lighthouse.va.gov/vro-app/v3/api-docs (based on vro-app's serviceUriPrefix)
  • For this to work, the Spring's OpenAPI implementation requires the X-Forwarded-Prefix header to be set correctly.
• The API Gateway serves up it's own API in api-gateway/src/main/java/gov/va/vro/ApiGatewayRestController.java. It can be extended to include domain-independent deployment info, health of containers, and stats.

Decision History

An API Gateway provides a single location to access all APIs provided by VRO, regardless of implementation language -- see ticket #1512. As a quick solution, it was implemented using Spring Cloud Gateway. It could be replaced with another API Gateway solution (e.g., Kong, which is used for other VA products) if the current implementation is insufficient or as new use cases arise.