Federation Gateway Developer Guide

Building and Packaging

Prerequisites

The build machine needs the following:

  1. Java version 1.8
  2. Maven version 3
  3. Connectivity to Maven Central (for most jars)
  4. Connectivity to Linux Foundation Nexus (for CDS jar)

Use below maven command to build and package the gateway service into a single jar:

mvn clean package

Development and Local Testing

This section provides information for developing and testing the federation gateway locally. We will run two instances of the gateway to depict two instance of Acumos federated to each other. In below scenario, we are going to run Acumos A and Acumos B for testing locally.

Launching

Start two microservice instances for development and testing as follows, with the appropriate version numbers:

java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks \
     -Djavax.net.ssl.trustStorePassword=acumos \
     -jar target/gateway-1.x.y-SNAPSHOT.jar \
     --spring.profiles.active="default,acumosa"

java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks \
     -Djavax.net.ssl.trustStorePassword=acumos \
     -jar target/gateway-1.x.y-SNAPSHOT.jar \
     --spring.profiles.active="default,acumosb"

REST Interface

The federation interface allows access via the federation gateway to information available in an Acumos system. The main exposed elements are catalogs, solutions, artifacts, and documents. The federation gateway allows pre-registered peers to retrieve a list of catalogs they are permitted to view. The peers can then list solutions and revisions of those solutions published in those catalogs. They can then retrieve metadata and content of artifacts referenced by those revisions. For each catalog a solution revision appears in, peers can retrieve a description and document metadata and content

The gateway requires mutual authentication; i.e., the client will be required to present a certificate. The gateway identifies a client as a pre-registered peer based on the certificates’ subjectName (which implies that the subjectName must be communicated to the Acumos system administrator when the peer is provisioned).

API

All APIs except the artifact and document content APIs, encode the response in JSON. The artifact and document content APIs return unencoded data. For other APIs, there is a top level envelope containing error information, and under the entry ‘responseBody’ it contains the actual content. All identifiers are UUIDs.

Online documentation of the API is available on each interface at /swagger-ui.html.

The following endpoints are defined on the public “E5” interface:

  • /catalogs

    List all visible (e.g. public) catalogs.

  • /solutions?catalogId={catalogId}

    List all solutions published to the specified catalog.

  • /solutions/{solutionId}

    Retrieve the specified solution, and its revisions.

  • /solutions/{solutionId}/revisions

    Retrieve the revisions of the specified solution.

  • /solutions/{solutionId}/revisions/{revisionId}[?catalogId={catalogId}]

    Retrieve details of the specified revision, including its artifacts. If the optional catalogId query parameter is specified, the description of the revision and any documents associated with it, from the specified catalog, will also be included.

  • /solutions/{solutionId}/revisions/{revisionId}/artifacts

    List all artifacts attached to a particular revision

  • /artifacts/{artifactId}/content

    Retrieve the content of the specified artifact

  • /revision/{revisionId}/documents?catalogId={catalogId}

    Retrieve documents associated with the specified revision in the specified catalog.

  • /documents/{documentId}/content

    Retrieve the content of the specified document

  • /modeldata

    Sends model data to supplier of the model.

  • /updateparams

    Sends parameters to deployed models.