api/appmgr_rest_api.yaml

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