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         '204':
 208           description: >
 209             policy instance successfully deleted
 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         '201':
 238           description: >
 239             Policy instance created
 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
 265       tags:
 266         - A1 Mediator
 267       operationId: a1.controller.get_policy_instance_status
 268       responses:
 269         '200':
 270           description: >
 271             The policy instance status.
 272             Returns a vector of statuses, where each contains a handler_id (opaque id of a RIC component that implements this policy) and the policy status as returned by that handler
 273           content:
 274             application/json:
 275               schema:
 276                 type: array
 277                 items:
 278                   type: object
 279                   properties:
 280                     handler_id:
 281                       type: string
 282                     status:
 283                       type: string
 284               example:
 285                 [{"handler_id": "1234-5678", "status" : "OK"}, {"handler_id": "abc-def", "status" : "NOT IMPLEMENTED"}]
 286         '404':
 287           description: >
 288             there is no policy instance with this policy_instance_id or there is no policy type with this policy_type_id
 289
 290
 291 components:
 292   schemas:
 293     policy_type_schema:
 294       type: object
 295       required:
 296       - name
 297       - description
 298       - policy_type_id
 299       - create_schema
 300       additionalProperties: false
 301       properties:
 302         name:
 303           type: string
 304           description: name of the policy type
 305         description:
 306           type: string
 307           description: description of the policy type
 308         policy_type_id:
 309           description: the integer of the policy type
 310           type: integer
 311         create_schema:
 312           type: object
 313           description: >
 314             jsonschema (following http://json-schema.org/draft-07/schema) of the CREATE payload to be sent to handlers of this policy
 315
 316     policy_type_id:
 317       description: >
 318         represents a policy type identifier. Currently this is restricted to an integer range.
 319       type: integer
 320       minimum: 20000
 321       maximum: 21023
 322
 323     policy_instance_id:
 324       description: >
 325         represents a policy instance identifier. UUIDs are advisable but can be any string
 326       type: string
 327       example: "3d2157af-6a8f-4a7c-810f-38c2f824bf12"
 328
 329     downstream_message_schema:
 330       type: object
 331       required:
 332         - operation
 333         - policy_type_id
 334         - policy_instance_id
 335         - payload
 336       additionalProperties: false
 337       properties:
 338         operation:
 339           description: the operation being performed
 340           type: string
 341           enum:
 342             - CREATE
 343             - DELETE
 344             - UPDATE
 345             - READ
 346         policy_type_id:
 347           "$ref": "#/components/schemas/policy_type_id"
 348         policy_instance_id:
 349           "$ref": "#/components/schemas/policy_instance_id"
 350         payload:
 351           description: payload for this operation
 352           type: object
 353       example:
 354         operation: CREATE
 355         policy_type_id: 12345678
 356         policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
 357         payload:
 358           enforce: true
 359           window_length: 10
 360           blocking_rate: 20
 361           trigger_threshold: 10
 362
 363     downstream_notification_schema:
 364       type: object
 365       required:
 366         - policy_type_id
 367         - policy_instance_id
 368         - handler_id
 369         - status
 370       additionalProperties: false
 371       properties:
 372         policy_type_id:
 373           "$ref": "#/components/schemas/policy_type_id"
 374         policy_instance_id:
 375           "$ref": "#/components/schemas/policy_instance_id"
 376         handler_id:
 377           description: >
 378             id of the policy handler
 379           type: string
 380         status:
 381           description: >
 382             the status of this policy instance in this handler
 383           type: string
 384       example:
 385         policy_type_id: 12345678
 386         policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
 387         handler_id: 1234-5678
 388         status: OK