Normalize to one trailing slash on Nexus URL
[federation.git] / 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"] }