near-rt-ric-simulator/api/OSC_2.1.0/openapi.yaml

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