Update AC, break out xapp contract from a1 api spec
[ric-plt/a1.git] / a1 / openapi.yaml
1 # ==================================================================================
2 #       Copyright (c) 2019 Nokia
3 #       Copyright (c) 2018-2019 AT&T Intellectual Property.
4 #
5 #   Licensed under the Apache License, Version 2.0 (the "License");
6 #   you may not use this file except in compliance with the License.
7 #   You may obtain a copy of the License at
8 #
9 #          http://www.apache.org/licenses/LICENSE-2.0
10 #
11 #   Unless required by applicable law or agreed to in writing, software
12 #   distributed under the License is distributed on an "AS IS" BASIS,
13 #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 #   See the License for the specific language governing permissions and
15 #   limitations under the License.
16 # ==================================================================================
17 openapi: 3.0.0
18 info:
19   version: 1.1.0
20   title: RIC A1
21 paths:
22   '/a1-p/healthcheck':
23     get:
24       description: >
25         Perform a healthcheck on a1
26       tags:
27         - A1 Mediator
28       operationId: a1.controller.get_healthcheck
29       responses:
30         200:
31           description: >
32             A1 is healthy.
33             Anything other than a 200 should be considered a1 as failing
34
35   '/a1-p/policytypes':
36     get:
37       description: "Get a list of all registered policy type ids"
38       tags:
39         - A1 Mediator
40       operationId: a1.controller.get_all_policy_types
41       responses:
42         200:
43           description: "list of all registered policy type ids"
44           content:
45             application/json:
46               schema:
47                 type: array
48                 items:
49                   "$ref": "#/components/schemas/policy_type_id"
50               example: [20000, 20020]
51
52   '/a1-p/policytypes/{policy_type_id}':
53     parameters:
54       - name: policy_type_id
55         in: path
56         required: true
57         schema:
58           "$ref": "#/components/schemas/policy_type_id"
59     get:
60       description: >
61         Get this policy type
62       tags:
63         - A1 Mediator
64       operationId: a1.controller.get_policy_type
65       responses:
66         '200':
67           description: "policy type successfully found"
68           content:
69             application/json:
70               schema:
71                 "$ref": "#/components/schemas/policy_type_schema"
72         '404':
73           description: >
74             policy type not found
75     delete:
76       description: >
77         Delete this policy type. Can only be performed if there are no instances of this type
78       tags:
79         - A1 Mediator
80       operationId: a1.controller.delete_policy_type
81       responses:
82         '204':
83           description: >
84             policy type successfully deleted
85         '400':
86           description: >
87             Policy type cannot be deleted because there are instances
88             All instances must be removed before a policy type can be deleted
89         '404':
90           description: >
91             policy type not found
92     put:
93       description: >
94         Create a new policy type .
95         Replace is not currently allowed; to replace, for now do a DELETE and then a PUT again.
96
97       tags:
98         - A1 Mediator
99       operationId: a1.controller.create_policy_type
100       requestBody:
101         content:
102           application/json:
103             schema:
104                "$ref": "#/components/schemas/policy_type_schema"
105             example:
106               name: admission_control_policy
107               description: various parameters to control admission of dual connection
108               policy_type_id: 20000
109               create_schema:
110                 $schema: 'http://json-schema.org/draft-07/schema#'
111                 type: object
112                 properties:
113                   enforce:
114                     type: boolean
115                     default: true
116                   window_length:
117                     type: integer
118                     default: 1
119                     minimum: 1
120                     maximum: 60
121                     description: Sliding window length (in minutes)
122                   blocking_rate:
123                     type: number
124                     default: 10
125                     minimum: 1
126                     maximum: 100
127                     description: '% Connections to block'
128                   trigger_threshold:
129                     type: integer
130                     default: 10
131                     minimum: 1
132                     description: Minimum number of events in window to trigger blocking
133                 additionalProperties: false
134
135       responses:
136         '201':
137           description: "policy type successfully created"
138         '400':
139           description: "illegal ID, or object already existed"
140
141   '/a1-p/policytypes/{policy_type_id}/policies':
142     parameters:
143       - name: policy_type_id
144         in: path
145         required: true
146         schema:
147           "$ref": "#/components/schemas/policy_type_id"
148     get:
149       description: "get a list of all policy instance ids for this policy type id"
150       tags:
151         - A1 Mediator
152       operationId: a1.controller.get_all_instances_for_type
153       responses:
154         200:
155           description: "list of all policy instance ids for this policy type id"
156           content:
157             application/json:
158               schema:
159                 type: array
160                 items:
161                   "$ref": "#/components/schemas/policy_instance_id"
162               example: ["3d2157af-6a8f-4a7c-810f-38c2f824bf12", "06911bfc-c127-444a-8eb1-1bffad27cc3d"]
163
164
165   '/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id}':
166     parameters:
167       - name: policy_type_id
168         in: path
169         required: true
170         schema:
171           "$ref": "#/components/schemas/policy_type_id"
172
173       - name: policy_instance_id
174         in: path
175         required: true
176         schema:
177           "$ref": "#/components/schemas/policy_instance_id"
178
179     get:
180       description: >
181         Retrieve the policy instance
182
183       tags:
184         - A1 Mediator
185       operationId: a1.controller.get_policy_instance
186       responses:
187         '200':
188           description: >
189             The policy instance.
190             the schema of this object is defined by the create_schema field of the policy type
191           content:
192             application/json:
193               schema:
194                 type: object
195         '404':
196           description: >
197             there is no policy instance with this policy_instance_id or there is no policy type with this policy_type_id
198
199     delete:
200       description: >
201         Delete this policy instance
202
203       tags:
204         - A1 Mediator
205       operationId: a1.controller.delete_policy_instance
206       responses:
207         '202':
208           description: >
209             policy instance deletion initiated
210         '404':
211           description: >
212             there is no policy instance with this policy_instance_id
213             or there is no policy type with this policy_type_id
214
215     put:
216       description: >
217         Create or replace a policy instance of type policy_type_id.
218         The schema of the PUT body is defined by the create_schema field of the policy type.
219
220       tags:
221         - A1 Mediator
222       operationId: a1.controller.create_or_replace_policy_instance
223       requestBody:
224         content:
225           application/json:
226             schema:
227               type: object
228               description: >
229                   the schema of this object is defined by the create_schema field of the policy type
230             example:
231               enforce: true
232               window_length: 10
233               blocking_rate: 20
234               trigger_threshold: 10
235
236       responses:
237         '202':
238           description: >
239             Policy instance creation initiated
240         '400':
241           description: >
242             Bad PUT body for this policy instance
243         '404':
244           description: >
245             There is no policy type with this policy_type_id
246
247   '/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id}/status':
248     parameters:
249       - name: policy_type_id
250         in: path
251         required: true
252         schema:
253           "$ref": "#/components/schemas/policy_type_id"
254
255       - name: policy_instance_id
256         in: path
257         required: true
258         schema:
259           "$ref": "#/components/schemas/policy_instance_id"
260
261     get:
262       description: >
263         Retrieve the policy instance status across all handlers of the policy
264         If this endpoint returns successfully (200), it is either IN EFFECT or NOT IN EFFECT.
265         IN EFFECT is returned if at least one policy handler in the RIC is implementing the policy
266         NOT IN EFFECT is returned otherwise
267         If a policy instance is successfully deleted, this endpoint will return a 404 (not a 200)
268       tags:
269         - A1 Mediator
270       operationId: a1.controller.get_policy_instance_status
271       responses:
272         '200':
273           description: >
274             successfully retrieved the status
275           content:
276             application/json:
277               schema:
278                 type: object
279                 properties:
280                   instance_status:
281                     type: string
282                     enum:
283                      - IN EFFECT
284                      - NOT IN EFFECT
285                   has_been_deleted:
286                     type: boolean
287                   created_at:
288                     type: string
289                     format: date-time
290
291         '404':
292           description: >
293             there is no policy instance with this policy_instance_id or there is no policy type with this policy_type_id
294
295 components:
296   schemas:
297     policy_type_schema:
298       type: object
299       required:
300       - name
301       - description
302       - policy_type_id
303       - create_schema
304       additionalProperties: false
305       properties:
306         name:
307           type: string
308           description: name of the policy type
309         description:
310           type: string
311           description: description of the policy type
312         policy_type_id:
313           description: the integer of the policy type
314           type: integer
315         create_schema:
316           type: object
317           description: >
318             jsonschema (following http://json-schema.org/draft-07/schema) of the CREATE payload to be sent to handlers of this policy
319
320     policy_type_id:
321       description: >
322         represents a policy type identifier. Currently this is restricted to an integer range.
323       type: integer
324       minimum: 1
325       maximum: 2147483647
326
327     policy_instance_id:
328       description: >
329         represents a policy instance identifier. UUIDs are advisable but can be any string
330       type: string
331       example: "3d2157af-6a8f-4a7c-810f-38c2f824bf12"