xapp-mgr-client/src/main/resources/xapp_manager_rest_api_v0_1_4.yaml

   1 # ========================LICENSE_START=================================
   2 # O-RAN-SC
   3 # %%
   4 # Copyright (C) 2019 AT&T Intellectual Property and Nokia
   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 # ========================LICENSE_END===================================
  18 swagger: '2.0'
  19 info:
  20   description: This is a draft API for RIC appmgr
  21   version: 0.1.4
  22   title: RIC appmgr
  23   license:
  24     name: Apache 2.0
  25     url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  26 host: hostname
  27 basePath: /ric/v1
  28 schemes:
  29   - http
  30 paths:
  31   /health/alive :
  32     get :
  33       summary     : Health check of xApp Manager - Liveness probe
  34       tags        :
  35         - health
  36       operationId : getHealthAlive
  37       responses   :
  38         '200' :
  39           description : Status of xApp Manager is ok
  40   /health/ready :
  41     get :
  42       summary     : Readiness check of xApp Manager - Readiness probe
  43       tags        :
  44         - health
  45       operationId : getHealthReady
  46       responses   :
  47         '200':
  48           description : xApp Manager is ready for service
  49         '503':
  50           description: xApp Manager is not ready for service
  51   /xapps:
  52     post:
  53       summary: Deploy a xapp
  54       tags:
  55         - xapp
  56       operationId: deployXapp
  57       consumes:
  58         - application/json
  59       produces:
  60         - application/json
  61       parameters:
  62         - name: xAppInfo
  63           in: body
  64           description: xApp information
  65           schema:
  66             type: object
  67             required:
  68               - name
  69             properties:
  70               name:
  71                 type: string
  72                 description: Name of the xApp.
  73                 example: xapp-dummy
  74               configName:
  75                 type: string
  76                 description: Name of the xApp configmap. Overrides the value given in Helm chart value file.
  77                 example: xapp-dummy-configmap
  78               namespace:
  79                 type: string
  80                 description: Name of the namespace to which xApp is deployed. Overrides the value given in Helm chart value file.
  81                 example: ricxapps
  82               serviceName:
  83                 type: string
  84                 description: Name of the service xApp is providing. Overrides the value given in Helm chart value file.
  85                 example: xapp-dummy-service
  86               imageRepo:
  87                 type: string
  88                 description: Name of the docker repository xApp is located. Overrides the value given in Helm chart value file.
  89                 example: xapprepo
  90               hostname:
  91                 type: string
  92                 description: Hostname for the pod. Used by messaging library. Overrides the value given in Helm chart value file.
  93                 example: xapp-dummy
  94       responses:
  95         '201':
  96           description: xApp successfully created
  97           schema:
  98             $ref: '#/definitions/Xapp'
  99         '400':
 100           description: Invalid input
 101         '500':
 102           description: Internal error
 103     get:
 104       summary: Returns the status of all xapps
 105       tags:
 106         - xapp
 107       operationId: getAllXapps
 108       produces:
 109         - application/json
 110       responses:
 111         '200':
 112           description: successful query of xApps
 113           schema:
 114             $ref: '#/definitions/AllXapps'
 115         '500':
 116           description: Internal error
 117   '/xapps/{xAppName}':
 118     get:
 119       summary: Returns the status of a given xapp
 120       tags:
 121         - xapp
 122       operationId: getXappByName
 123       produces:
 124         - application/json
 125       parameters:
 126         - name: xAppName
 127           in: path
 128           description: Name of xApp
 129           required: true
 130           type: string
 131       responses:
 132         '200':
 133           description: successful operation
 134           schema:
 135             $ref: '#/definitions/Xapp'
 136         '400':
 137           description: Invalid ID supplied
 138         '404':
 139           description: Xapp not found
 140         '500':
 141           description: Internal error
 142     delete:
 143       summary: Undeploy an existing xapp
 144       tags:
 145         - xapp
 146       operationId: undeployXapp
 147       parameters:
 148         - name: xAppName
 149           in: path
 150           description: Xapp to be undeployed
 151           required: true
 152           type: string
 153       responses:
 154         '204':
 155           description: Successful deletion of xApp
 156         '400':
 157           description: Invalid xApp name supplied
 158         '500':
 159           description: Internal error
 160   '/xapps/{xAppName}/instances/{xAppInstanceName}':
 161     get:
 162       summary: Returns the status of a given xapp
 163       tags:
 164         - xapp
 165       operationId: getXappInstanceByName
 166       produces:
 167         - application/json
 168       parameters:
 169         - name: xAppName
 170           in: path
 171           description: Name of xApp
 172           required: true
 173           type: string
 174         - name: xAppInstanceName
 175           in: path
 176           description: Name of xApp instance to get information
 177           required: true
 178           type: string
 179       responses:
 180         '200':
 181           description: successful operation
 182           schema:
 183             $ref: '#/definitions/XappInstance'
 184         '400':
 185           description: Invalid name supplied
 186         '404':
 187           description: Xapp not found
 188         '500':
 189           description: Internal error
 190   /config:
 191     post:
 192       summary: Create xApp config
 193       tags:
 194         - xapp
 195       operationId: createXappConfig
 196       consumes:
 197         - application/json
 198       produces:
 199         - application/json
 200       parameters:
 201         - name: XAppConfig
 202           in: body
 203           description: xApp config
 204           schema:
 205             $ref: '#/definitions/XAppConfig'
 206       responses:
 207         '201':
 208           description: xApp config successfully created
 209           schema:
 210             $ref: '#/definitions/XAppConfig'
 211         '400':
 212           description: Invalid input
 213         '422':
 214           description: Validation of configuration failed
 215         '500':
 216           description: Internal error
 217     put:
 218       summary: Modify xApp config
 219       tags:
 220         - xapp
 221       operationId: ModifyXappConfig
 222       consumes:
 223         - application/json
 224       produces:
 225         - application/json
 226       parameters:
 227         - name: XAppConfig
 228           in: body
 229           description: xApp config
 230           schema:
 231             $ref: '#/definitions/XAppConfig'
 232       responses:
 233         '200':
 234           description: xApp config successfully modified
 235           schema:
 236             $ref: '#/definitions/XAppConfig'
 237         '400':
 238           description: Invalid input
 239         '422':
 240           description: Validation of configuration failed
 241         '500':
 242           description: Internal error
 243     get:
 244       summary: Returns the configuration of all xapps
 245       tags:
 246         - xapp
 247       operationId: getAllXappConfig
 248       produces:
 249         - application/json
 250       responses:
 251         '200':
 252           description: successful query of xApp config
 253           schema:
 254             $ref: '#/definitions/AllXappConfig'
 255         '500':
 256           description: Internal error
 257     delete:
 258       summary: Delete xApp configuration
 259       tags:
 260         - xapp
 261       operationId: deleteXappConfig
 262       parameters:
 263         - name: ConfigMetadata
 264           in: body
 265           description: xApp configuration information
 266           schema:
 267             $ref: '#/definitions/ConfigMetadata'
 268       responses:
 269         '204':
 270           description: Successful deletion of xApp
 271         '400':
 272           description: Invalid parameters supplied
 273         '500':
 274           description: Internal error
 275   /subscriptions:
 276     post:
 277       summary: Subscribe event
 278       tags:
 279         - xapp
 280         - subscriptions
 281       operationId: addSubscription
 282       consumes:
 283         - application/json
 284       produces:
 285         - application/json
 286       parameters:
 287         - name: subscriptionRequest
 288           in: body
 289           description: New subscription
 290           required: true
 291           schema:
 292             $ref: '#/definitions/subscriptionRequest'
 293       responses:
 294         '200':
 295           description: Subscription successful
 296           schema:
 297             $ref: '#/definitions/subscriptionResponse'
 298         '400':
 299           description: Invalid input
 300     get:
 301       summary: Returns all subscriptions
 302       tags:
 303         - xapp
 304         - subscriptions
 305       operationId: getSubscriptions
 306       produces:
 307         - application/json
 308       responses:
 309         '200':
 310           description: successful query of subscriptions
 311           schema:
 312             $ref: '#/definitions/allSubscriptions'
 313   '/subscriptions/{subscriptionId}':
 314     get:
 315       summary: Returns the information of subscription
 316       tags:
 317         - xapp
 318         - subscriptions
 319       operationId: getSubscriptionById
 320       produces:
 321         - application/json
 322       parameters:
 323         - name: subscriptionId
 324           in: path
 325           description: ID of subscription
 326           required: true
 327           type: string
 328       responses:
 329         '200':
 330           description: successful operation
 331           schema:
 332             $ref: '#/definitions/subscription'
 333         '400':
 334           description: Invalid ID supplied
 335         '404':
 336           description: Subscription not found
 337     put:
 338       summary: Modify event subscription
 339       tags:
 340         - xapp
 341         - subscriptions
 342       operationId: modifySubscription
 343       consumes:
 344         - application/json
 345       produces:
 346         - application/json
 347       parameters:
 348         - name: subscriptionId
 349           in: path
 350           description: ID of subscription
 351           required: true
 352           type: string
 353         - in: body
 354           name: subscriptionRequest
 355           description: Modified subscription
 356           required: true
 357           schema:
 358             $ref: '#/definitions/subscriptionRequest'
 359       responses:
 360         '200':
 361           description: Subscription modification successful
 362           schema:
 363             $ref: '#/definitions/subscriptionResponse'
 364         '400':
 365           description: Invalid input
 366     delete:
 367       summary: Unsubscribe event
 368       tags:
 369         - xapp
 370         - subscriptions
 371       description: ''
 372       operationId: deleteSubscription
 373       parameters:
 374         - name: subscriptionId
 375           in: path
 376           description: ID of subscription
 377           required: true
 378           type: string
 379       responses:
 380         '204':
 381           description: Successful deletion of subscription
 382         '400':
 383           description: Invalid subscription supplied
 384 definitions:
 385   AllXapps:
 386     type: array
 387     items:
 388       $ref: '#/definitions/Xapp'
 389   Xapp:
 390     type: object
 391     required:
 392       - name
 393     properties:
 394       name:
 395         type: string
 396         example: xapp-dummy
 397       status:
 398         type: string
 399         description: xapp status in the RIC
 400         enum:
 401           - unknown
 402           - deployed
 403           - deleted
 404           - superseded
 405           - failed
 406           - deleting
 407       version:
 408         type: string
 409         example: 1.2.3
 410       instances:
 411         type: array
 412         items:
 413           $ref: '#/definitions/XappInstance'
 414   XappInstance:
 415     type: object
 416     required:
 417       - name
 418     properties:
 419       name:
 420         type: string
 421         example: xapp-dummy-6cd577d9-4v255
 422       status:
 423         type: string
 424         description: xapp instance status
 425         enum:
 426           - pending
 427           - running
 428           - succeeded
 429           - failed
 430           - unknown
 431           - completed
 432           - crashLoopBackOff
 433       ip:
 434         type: string
 435         example: 192.168.0.1
 436       port:
 437         type: integer
 438         example: 32300
 439       txMessages:
 440         type: array
 441         items:
 442           type: string
 443           example: ControlIndication
 444       rxMessages:
 445         type: array
 446         items:
 447           type: string
 448           example: LoadIndication
 449   ConfigMetadata:
 450     type: object
 451     required:
 452       - name
 453       - configName
 454       - namespace
 455     properties:
 456       name:
 457         type: string
 458         description: Name of the xApp
 459         example: xapp-dummy
 460       configName:
 461         type: string
 462         description: Name of the config map
 463         example: xapp-dummy-config-map
 464       namespace:
 465         type: string
 466         description: Name of the namespace
 467         example: ricxapp
 468   XAppConfig:
 469     type: object
 470     required:
 471       - metadata
 472       - descriptor
 473       - config
 474     properties:
 475       metadata:
 476         $ref: '#/definitions/ConfigMetadata'
 477       descriptor:
 478         type: object
 479         description: Schema of configuration in JSON format
 480       config:
 481         type: object
 482         description: Configuration in JSON format
 483   AllXappConfig:
 484     type: array
 485     items:
 486       $ref: '#/definitions/XAppConfig'
 487   subscriptionRequest:
 488     type: object
 489     required:
 490       - targetUrl
 491       - eventType
 492       - maxRetries
 493       - retryTimer
 494     properties:
 495       targetUrl:
 496         type: string
 497         example: 'http://localhost:11111/apps/webhook/'
 498       eventType:
 499         type: string
 500         description: Event which is subscribed
 501         enum:
 502           - created
 503           - deleted
 504           - all
 505       maxRetries:
 506         type: integer
 507         description: Maximum number of retries
 508         example: 11
 509       retryTimer:
 510         type: integer
 511         description: Time in seconds to wait before next retry
 512         example: 22
 513   subscriptionResponse:
 514     type: object
 515     properties:
 516       id:
 517         type: string
 518         example: 1ILBltYYzEGzWRrVPZKmuUmhwcc
 519       version:
 520         type: integer
 521         example: 2
 522       eventType:
 523         type: string
 524         description: Event which is subscribed
 525         enum:
 526           - created
 527           - deleted
 528           - updated
 529           - all
 530   allSubscriptions:
 531     type: array
 532     items:
 533       $ref: '#/definitions/subscription'
 534   subscription:
 535     type: object
 536     properties:
 537       id:
 538         type: string
 539         example: 1ILBltYYzEGzWRrVPZKmuUmhwcc
 540       targetUrl:
 541         type: string
 542         example: 'http://localhost:11111/apps/webhook/'
 543       eventType:
 544         type: string
 545         description: Event which is subscribed
 546         enum:
 547           - created
 548           - deleted
 549           - updated
 550           - all
 551       maxRetries:
 552         type: integer
 553         description: Maximum number of retries
 554         example: 11
 555       retryTimer:
 556         type: integer
 557         description: Time in seconds to wait before next retry
 558         example: 22
 559   subscriptionNotification:
 560     type: object
 561     properties:
 562       id:
 563         type: string
 564         example: 1ILBltYYzEGzWRrVPZKmuUmhwcc
 565       version:
 566         type: integer
 567         example: 2
 568       eventType:
 569         type: string
 570         description: Event to be notified
 571         enum:
 572           - created
 573           - deleted
 574           - updated
 575       xApps:
 576         $ref: '#/definitions/AllXapps'