Aligns with CDS 1.15
[federation.git] / docs / federated-gateway.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 Federated 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
35 Use below maven command to build and package the gateway service into a single jar::
36
37         mvn clean package
38
39 Development and Local Testing
40 -----------------------------
41
42 This section provides information for developing and testing the federaton gateway locally. We will run two instances of the gateway to depict 2 instance of acumos federated to each other.
43 In below scenario, we are going to run Acumos A and Acumos B for testing locally.
44
45 Launching
46 ~~~~~~~~~
47
48 Start the microservice for development and testing like this::
49
50         java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks -Djavax.net.ssl.trustStorePassword=acumos -jar target/federated-gateway-1.0.0-SNAPSHOT.jar --spring.profiles.active="default,acumosa" 
51
52         java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks -Djavax.net.ssl.trustStorePassword=acumos -jar target/federated-gateway-1.0.0-SNAPSHOT.jar --spring.profiles.active="default,acumosb"
53
54 REST interface
55 --------------
56
57 The federation interface allows access via the federation gateway to informationavailable in an Acumos system. The main category of information that is exposed via the gateway is solution information: solution/revision/artifact and artifact content.
58 The federation gateway allows access from pre-registered peers via a REST interface running over HTTPS/SSL/TLS. 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).
59
60 API
61 ~~~
62
63 All APIs encode the response in JSON. There is a top level envelope containing error information, and under the entry 'responseBody' it contains the actual content. All identifiers are UUIDs.
64
65 * /solutions
66    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.
67
68 * /solutions/{solutionId}
69   Retrieve one solution details.
70
71 * /solutions/{solutionId}/revisions
72   List all revisions for a given solution.
73
74 * /solutions/{solutionId}/revisions/{revisionId}
75   Retrieve one revision details
76
77 * /solutions/{solutionId}/revisions/{revisionId}/artifacts
78   List all artifacts attached to a particular revision
79
80 * /artifacts/{artifactId}
81   Retrieve one artifact details
82
83 * /artifacts/{artifactId}/download
84   Download the artifact content.
85
86 Example of solutions selector:
87
88  { "modelTypeCode":"CL" } will select all CLassifiers
89
90 Multiple values for a solution attribute are allowed and ORed
91
92  { "modelTypeCode":["CL","PR"] } will select all CLassifiers and PRedictors