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