Towards Resiliency.
[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.0.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             text/plain:
277               schema:
278                 type: string
279                 enum:
280                  - IN EFFECT
281                  - NOT IN EFFECT
282         '404':
283           description: >
284             there is no policy instance with this policy_instance_id or there is no policy type with this policy_type_id
285
286 components:
287   schemas:
288     policy_type_schema:
289       type: object
290       required:
291       - name
292       - description
293       - policy_type_id
294       - create_schema
295       additionalProperties: false
296       properties:
297         name:
298           type: string
299           description: name of the policy type
300         description:
301           type: string
302           description: description of the policy type
303         policy_type_id:
304           description: the integer of the policy type
305           type: integer
306         create_schema:
307           type: object
308           description: >
309             jsonschema (following http://json-schema.org/draft-07/schema) of the CREATE payload to be sent to handlers of this policy
310
311     policy_type_id:
312       description: >
313         represents a policy type identifier. Currently this is restricted to an integer range.
314       type: integer
315       minimum: 20000
316       maximum: 21023
317
318     policy_instance_id:
319       description: >
320         represents a policy instance identifier. UUIDs are advisable but can be any string
321       type: string
322       example: "3d2157af-6a8f-4a7c-810f-38c2f824bf12"
323
324     downstream_message_schema:
325       type: object
326       required:
327         - operation
328         - policy_type_id
329         - policy_instance_id
330         - payload
331       additionalProperties: false
332       properties:
333         operation:
334           description: the operation being performed
335           type: string
336           enum:
337             - CREATE
338             - DELETE
339             - UPDATE
340             - READ
341         policy_type_id:
342           "$ref": "#/components/schemas/policy_type_id"
343         policy_instance_id:
344           "$ref": "#/components/schemas/policy_instance_id"
345         payload:
346           description: payload for this operation
347           type: object
348       example:
349         operation: CREATE
350         policy_type_id: 12345678
351         policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
352         payload:
353           enforce: true
354           window_length: 10
355           blocking_rate: 20
356           trigger_threshold: 10
357
358     downstream_notification_schema:
359       type: object
360       required:
361         - policy_type_id
362         - policy_instance_id
363         - handler_id
364         - status
365       additionalProperties: false
366       properties:
367         policy_type_id:
368           "$ref": "#/components/schemas/policy_type_id"
369         policy_instance_id:
370           "$ref": "#/components/schemas/policy_instance_id"
371         handler_id:
372           description: >
373             id of the policy handler
374           type: string
375         status:
376           description: >
377             the status of this policy instance in this handler
378           type: string
379           enum:
380             - OK
381             - ERROR
382             - DELETED
383       example:
384         policy_type_id: 12345678
385         policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
386         handler_id: 1234-5678
387         status: OK