Add sdl healthcheck to a1's healthcheck
[ric-plt/a1.git] / a1 / openapi.yaml
1 # ==================================================================================
2 #       Copyright (c) 2019-2020 Nokia
3 #       Copyright (c) 2018-2020 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: 2.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         503:
52           description: "Potentially transient backend database error. Client should attempt to retry later."
53
54   '/a1-p/policytypes/{policy_type_id}':
55     parameters:
56       - name: policy_type_id
57         in: path
58         required: true
59         schema:
60           "$ref": "#/components/schemas/policy_type_id"
61     get:
62       description: >
63         Get this policy type
64       tags:
65         - A1 Mediator
66       operationId: a1.controller.get_policy_type
67       responses:
68         '200':
69           description: "policy type successfully found"
70           content:
71             application/json:
72               schema:
73                 "$ref": "#/components/schemas/policy_type_schema"
74         '404':
75           description: >
76             policy type not found
77         '503':
78           description: "Potentially transient backend database error. Client should attempt to retry later."
79     delete:
80       description: >
81         Delete this policy type. Can only be performed if there are no instances of this type
82       tags:
83         - A1 Mediator
84       operationId: a1.controller.delete_policy_type
85       responses:
86         '204':
87           description: >
88             policy type successfully deleted
89         '400':
90           description: >
91             Policy type cannot be deleted because there are instances
92             All instances must be removed before a policy type can be deleted
93         '404':
94           description: >
95             policy type not found
96         '503':
97           description: "Potentially transient backend database error. Client should attempt to retry later."
98     put:
99       description: >
100         Create a new policy type .
101         Replace is not currently allowed; to replace, for now do a DELETE and then a PUT again.
102
103       tags:
104         - A1 Mediator
105       operationId: a1.controller.create_policy_type
106       requestBody:
107         content:
108           application/json:
109             schema:
110                "$ref": "#/components/schemas/policy_type_schema"
111             example:
112               name: admission_control_policy
113               description: various parameters to control admission of dual connection
114               policy_type_id: 20000
115               create_schema:
116                 $schema: 'http://json-schema.org/draft-07/schema#'
117                 type: object
118                 properties:
119                   enforce:
120                     type: boolean
121                     default: true
122                   window_length:
123                     type: integer
124                     default: 1
125                     minimum: 1
126                     maximum: 60
127                     description: Sliding window length (in minutes)
128                   blocking_rate:
129                     type: number
130                     default: 10
131                     minimum: 1
132                     maximum: 100
133                     description: '% Connections to block'
134                   trigger_threshold:
135                     type: integer
136                     default: 10
137                     minimum: 1
138                     description: Minimum number of events in window to trigger blocking
139                 additionalProperties: false
140
141       responses:
142         '201':
143           description: "policy type successfully created"
144         '400':
145           description: "illegal ID, or object already existed"
146         '503':
147           description: "Potentially transient backend database error. Client should attempt to retry later."
148
149   '/a1-p/policytypes/{policy_type_id}/policies':
150     parameters:
151       - name: policy_type_id
152         in: path
153         required: true
154         schema:
155           "$ref": "#/components/schemas/policy_type_id"
156     get:
157       description: "get a list of all policy instance ids for this policy type id"
158       tags:
159         - A1 Mediator
160       operationId: a1.controller.get_all_instances_for_type
161       responses:
162         200:
163           description: "list of all policy instance ids for this policy type id"
164           content:
165             application/json:
166               schema:
167                 type: array
168                 items:
169                   "$ref": "#/components/schemas/policy_instance_id"
170               example: ["3d2157af-6a8f-4a7c-810f-38c2f824bf12", "06911bfc-c127-444a-8eb1-1bffad27cc3d"]
171         '503':
172           description: "Potentially transient backend database error. Client should attempt to retry later."
173
174
175   '/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id}':
176     parameters:
177       - name: policy_type_id
178         in: path
179         required: true
180         schema:
181           "$ref": "#/components/schemas/policy_type_id"
182
183       - name: policy_instance_id
184         in: path
185         required: true
186         schema:
187           "$ref": "#/components/schemas/policy_instance_id"
188
189     get:
190       description: >
191         Retrieve the policy instance
192
193       tags:
194         - A1 Mediator
195       operationId: a1.controller.get_policy_instance
196       responses:
197         '200':
198           description: >
199             The policy instance.
200             the schema of this object is defined by the create_schema field of the policy type
201           content:
202             application/json:
203               schema:
204                 type: object
205         '404':
206           description: >
207             there is no policy instance with this policy_instance_id or there is no policy type with this policy_type_id
208         '503':
209           description: "Potentially transient backend database error. Client should attempt to retry later."
210
211     delete:
212       description: >
213         Delete this policy instance
214
215       tags:
216         - A1 Mediator
217       operationId: a1.controller.delete_policy_instance
218       responses:
219         '202':
220           description: >
221             policy instance deletion initiated
222         '404':
223           description: >
224             there is no policy instance with this policy_instance_id or there is no policy type with this policy_type_id
225         '503':
226           description: "Potentially transient backend database error. Client should attempt to retry later."
227
228     put:
229       description: >
230         Create or replace a policy instance of type policy_type_id.
231         The schema of the PUT body is defined by the create_schema field of the policy type.
232
233       tags:
234         - A1 Mediator
235       operationId: a1.controller.create_or_replace_policy_instance
236       requestBody:
237         content:
238           application/json:
239             schema:
240               type: object
241               description: >
242                   the schema of this object is defined by the create_schema field of the policy type
243             example:
244               enforce: true
245               window_length: 10
246               blocking_rate: 20
247               trigger_threshold: 10
248
249       responses:
250         '202':
251           description: >
252             Policy instance creation initiated
253         '400':
254           description: >
255             Bad PUT body for this policy instance
256         '404':
257           description: >
258             There is no policy type with this policy_type_id
259         '503':
260           description: "Potentially transient backend database error. Client should attempt to retry later."
261
262   '/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id}/status':
263     parameters:
264       - name: policy_type_id
265         in: path
266         required: true
267         schema:
268           "$ref": "#/components/schemas/policy_type_id"
269
270       - name: policy_instance_id
271         in: path
272         required: true
273         schema:
274           "$ref": "#/components/schemas/policy_instance_id"
275
276     get:
277       description: >
278         Retrieve the policy instance status across all handlers of the policy
279         If this endpoint returns successfully (200), it is either IN EFFECT or NOT IN EFFECT.
280         IN EFFECT is returned if at least one policy handler in the RIC is implementing the policy
281         NOT IN EFFECT is returned otherwise
282         If a policy instance is successfully deleted, this endpoint will return a 404 (not a 200)
283       tags:
284         - A1 Mediator
285       operationId: a1.controller.get_policy_instance_status
286       responses:
287         '200':
288           description: >
289             successfully retrieved the status
290           content:
291             application/json:
292               schema:
293                 type: object
294                 properties:
295                   instance_status:
296                     type: string
297                     enum:
298                      - IN EFFECT
299                      - NOT IN EFFECT
300                   has_been_deleted:
301                     type: boolean
302                   created_at:
303                     type: string
304                     format: date-time
305
306         '404':
307           description: >
308             there is no policy instance with this policy_instance_id or there is no policy type with this policy_type_id
309         '503':
310           description: "Potentially transient backend database error. Client should attempt to retry later."
311
312 components:
313   schemas:
314     policy_type_schema:
315       type: object
316       required:
317       - name
318       - description
319       - policy_type_id
320       - create_schema
321       additionalProperties: false
322       properties:
323         name:
324           type: string
325           description: name of the policy type
326         description:
327           type: string
328           description: description of the policy type
329         policy_type_id:
330           description: the integer of the policy type
331           type: integer
332         create_schema:
333           type: object
334           description: >
335             jsonschema (following http://json-schema.org/draft-07/schema) of the CREATE payload to be sent to handlers of this policy
336
337     policy_type_id:
338       description: >
339         represents a policy type identifier. Currently this is restricted to an integer range.
340       type: integer
341       minimum: 1
342       maximum: 2147483647
343
344     policy_instance_id:
345       description: >
346         represents a policy instance identifier. UUIDs are advisable but can be any string
347       type: string
348       example: "3d2157af-6a8f-4a7c-810f-38c2f824bf12"