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"