Normalize to one trailing slash on Nexus URL
[federation.git] / docs / selectors.rst
1 .. ===============LICENSE_START=======================================================
2 .. Acumos CC-BY-4.0
3 .. ===================================================================================
4 .. Copyright (C) 2019 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 .. _selecting:
20
21 Selectors and Finding Solutions
22 -------------------------------
23
24 The Acumos federation gateway supports retrieving solutions from a peer
25 instance of Acumos.  Usually, though, what is desired is to retrieve a subset
26 of the solutions, and this is done by specifying a "selector" as a query
27 parameter on the HTTP GET from the peer federation gateway.  The value of the
28 selector is the Base64 encoding of a JSON object, with keys specifying
29 constraints on the set of solutions to be returned.  For example, to specify
30 that the name of the solution must be "hello," the JSON object might look like::
31
32     {"name":"hello"}
33
34 The Base64 encoding of this is::
35
36     eyJuYW1lIjoiaGVsbG8ifQ==
37
38 And the URL for an HTTP GET with this selector might be::
39
40     https://example.org/solutions?selector=eyJuYW1lIjoiaGVsbG8ifQ%3D%3D
41
42 The keys supported in the selector object are:
43
44 * active
45
46   Boolean, either true or false.  Defaults to true.  If true, only active
47   solutions will be returned.  If false, only inactive solutions will be
48   returned.
49
50 * catalogId
51
52   String.  If specified, only solutions from the specified catalog will be
53   returned.
54
55 * modelTypeCode
56
57   String or array of strings.  If specified, only solutions with one of the
58   specified modelTypeCodes will be returned.
59
60 * modified
61
62   Integer.  Defaults to 1.  A timestamp specified as the number of seconds since
63   January 1, 1970, 00:00:00 GMT.  Only solutions modified at or after the
64   specified timestamp will be returned.
65
66 * name
67
68   String.  If specified, only solutions with the specified name will be
69   returned.
70
71 * solutionId
72
73   String.  If specified, only the specified solution will be returned.
74
75 * toolkitTypeCode
76
77   String or array of strings.  If specified, only solutions with one of the
78   specified toolkitTypeCodes will be returned.
79
80 * tags
81
82   String or array of strings.  If specified, only solutions that have at
83   least one of the specified tags will be returned.
84
85 Note: String comparison uses an exact match.
86
87 Note: Only solutions that meet all of the specified constraints will be returned.
88
89 Note: A federation gateway can be configured with additional default values as
90 well as overrides of user specified values.
91
92 Note: To get "all" solutions, don't specify a selector on the HTTP request (or
93 specify one without any of the above keys).  Default constraints will still
94 be applied, so only active solutions modified after
95 January 1st, 1970 at 00:00:00 GMT will be returned.