docs/developer-guide.rst

   1 .. ===============LICENSE_START=======================================================
   2 .. Acumos CC-BY-4.0
   3 .. ===================================================================================
   4 .. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
   5 .. ===================================================================================
   6 .. This Acumos documentation file is distributed by AT&T and Tech Mahindra
   7 .. under the Creative Commons Attribution 4.0 International License (the "License");
   8 .. you may not use this file except in compliance with the License.
   9 .. You may obtain a copy of the License at
  10 ..
  11 .. http://creativecommons.org/licenses/by/4.0
  12 ..
  13 .. This file is distributed on an "AS IS" BASIS,
  14 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15 .. See the License for the specific language governing permissions and
  16 .. limitations under the License.
  17 .. ===============LICENSE_END=========================================================
  18
  19 ==================================
  20 Federation Gateway Developer Guide
  21 ==================================
  22
  23 Building and Packaging
  24 ----------------------
  25
  26 Prerequisites
  27 ~~~~~~~~~~~~~
  28
  29 The build machine needs the following:
  30
  31 1. Java version 1.8
  32 2. Maven version 3
  33 3. Connectivity to Maven Central (for most jars)
  34 4. Connectivity to Linux Foundation Nexus (for CDS jar)
  35
  36
  37 Use below maven command to build and package the gateway service into a single jar::
  38
  39         mvn clean package
  40
  41 Development and Local Testing
  42 -----------------------------
  43
  44 This section provides information for developing and testing the federaton gateway locally.
  45 We will run two instances of the gateway to depict two instance of Acumos federated to each other.
  46 In below scenario, we are going to run Acumos A and Acumos B for testing locally.
  47
  48 Launching
  49 ~~~~~~~~~
  50
  51 Start two microservice instances for development and testing as follows, with the appropriate version numbers::
  52
  53     java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks \
  54          -Djavax.net.ssl.trustStorePassword=acumos \
  55          -jar target/gateway-1.x.y-SNAPSHOT.jar \
  56          --spring.profiles.active="default,acumosa"
  57
  58     java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks \
  59          -Djavax.net.ssl.trustStorePassword=acumos \
  60          -jar target/gateway-1.x.y-SNAPSHOT.jar \
  61          --spring.profiles.active="default,acumosb"
  62
  63
  64 REST Interface
  65 --------------
  66
  67 The federation interface allows access via the federation gateway to information available in an Acumos system.
  68 The main category of information that is exposed via the gateway is solution information: solution/revision/artifact and artifact content.
  69 The federation gateway allows access from pre-registered peers via a REST interface running over HTTPS/SSL/TLS.
  70 The gateway requires mutual authentication; i.e., the client will be required to present a certificate.
  71 The gateway identifies a client as a pre-registered peer based on the certificates' subjectName
  72 (which implies that the subjectName must be communicated to the Acumos system administrator when the peer is provisioned).
  73
  74 API
  75 ~~~
  76
  77 All APIs encode the response in JSON.
  78 There is a top level envelope containing error information, and under the entry 'responseBody' it contains the actual content.
  79 All identifiers are UUIDs.
  80 The following endpoints are defined:
  81
  82 * /solutions
  83
  84   List all public solutions. Accepts a query parameter, 'selector', which contains a JSON object with selection criteria, base64 encoded. Acceptable selection criteria are the solution object attributes. The entries are ANDed (see :ref:`selecting`).
  85
  86 * /solutions/{solutionId}
  87
  88   Retrieve one solution details.
  89
  90 * /solutions/{solutionId}/revisions
  91
  92   List all revisions for a given solution.
  93
  94 * /solutions/{solutionId}/revisions/{revisionId}
  95
  96   Retrieve one revision details
  97
  98 * /solutions/{solutionId}/revisions/{revisionId}/artifacts
  99
 100   List all artifacts attached to a particular revision
 101
 102 * /artifacts/{artifactId}
 103
 104   Retrieve one artifact details
 105
 106 * /artifacts/{artifactId}/download
 107
 108   Download the artifact content.
 109
 110 Example of solutions selector: The following will select all CLassifiers::
 111
 112     { "modelTypeCode":"CL" }
 113
 114 Multiple values for a solution attribute are allowed and ORed.  The following will select all CLassifiers and PRedictors::
 115
 116     { "modelTypeCode":["CL","PR"] }