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"
 332
 333     downstream_message_schema:
 334       type: object
 335       required:
 336         - operation
 337         - policy_type_id
 338         - policy_instance_id
 339         - payload
 340       additionalProperties: false
 341       properties:
 342         operation:
 343           description: the operation being performed
 344           type: string
 345           enum:
 346             - CREATE
 347             - DELETE
 348             - UPDATE
 349             - READ
 350         policy_type_id:
 351           "$ref": "#/components/schemas/policy_type_id"
 352         policy_instance_id:
 353           "$ref": "#/components/schemas/policy_instance_id"
 354         payload:
 355           description: payload for this operation
 356           type: object
 357       example:
 358         operation: CREATE
 359         policy_type_id: 12345678
 360         policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
 361         payload:
 362           enforce: true
 363           window_length: 10
 364           blocking_rate: 20
 365           trigger_threshold: 10
 366
 367     downstream_notification_schema:
 368       type: object
 369       required:
 370         - policy_type_id
 371         - policy_instance_id
 372         - handler_id
 373         - status
 374       additionalProperties: false
 375       properties:
 376         policy_type_id:
 377           "$ref": "#/components/schemas/policy_type_id"
 378         policy_instance_id:
 379           "$ref": "#/components/schemas/policy_instance_id"
 380         handler_id:
 381           description: >
 382             id of the policy handler
 383           type: string
 384         status:
 385           description: >
 386             the status of this policy instance in this handler
 387           type: string
 388           enum:
 389             - OK
 390             - ERROR
 391             - DELETED
 392       example:
 393         policy_type_id: 12345678
 394         policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
 395         handler_id: 1234-5678
 396         status: OK