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   /deregister:
 356     post:
 357       summary: Deregister an existing xApp
 358       tags:
 359         - xapp
 360         - registration
 361       operationId: deregisterXapp
 362       consumes:
 363         - application/json
 364       parameters:
 365         - name: deregisterRequest
 366           in: body
 367           description: Xapp to be unregistered
 368           required: true
 369           schema:
 370             $ref: '#/definitions/deregisterRequest'
 371       responses:
 372         '204':
 373           description: Successful deregistration of xApp
 374         '400':
 375           description: Invalid xApp name supplied
 376         '500':
 377           description: Internal error
 378 definitions:
 379   AllDeployableXapps:
 380     type: array
 381     items:
 382       type: string
 383   AllDeployedXapps:
 384     type: array
 385     items:
 386       $ref: '#/definitions/Xapp'
 387   Xapp:
 388     type: object
 389     required:
 390       - name
 391     properties:
 392       name:
 393         type: string
 394       status:
 395         type: string
 396         description: xapp status in the RIC
 397         enum:
 398           - unknown
 399           - deployed
 400           - deleted
 401           - superseded
 402           - failed
 403           - deleting
 404       version:
 405         type: string
 406       instances:
 407         type: array
 408         items:
 409           $ref: '#/definitions/XappInstance'
 410   XappInstance:
 411     type: object
 412     required:
 413       - name
 414     properties:
 415       name:
 416         type: string
 417       status:
 418         type: string
 419         description: xapp instance status
 420         enum:
 421           - pending
 422           - running
 423           - succeeded
 424           - failed
 425           - unknown
 426           - completed
 427           - crashLoopBackOff
 428       ip:
 429         type: string
 430       port:
 431         type: integer
 432       txMessages:
 433         type: array
 434         items:
 435           type: string
 436       rxMessages:
 437         type: array
 438         items:
 439           type: string
 440       policies:
 441          type: array
 442          items:
 443            type: integer
 444   XappDescriptor:
 445     type: object
 446     required:
 447       - xappName
 448     properties:
 449       xappName:
 450         type: string
 451         description: Name of the xApp in helm chart
 452       helmVersion:
 453         type: string
 454         description: The exact xapp helm chart version to install
 455       releaseName:
 456         type: string
 457         description: Name of the xapp to be visible in Kubernetes
 458       namespace:
 459         type: string
 460         description: Name of the namespace to which xApp is deployed. Overrides the value given in Helm chart value file.
 461       overrideFile:
 462         type: object
 463         description: JSON string of override file for 'helm install' command
 464   XappDescriptorList:
 465     type: array
 466     items:
 467       $ref: '#/definitions/XappDescriptor'
 468   ConfigMetadata:
 469     type: object
 470     required:
 471       - xappName
 472       - namespace
 473     properties:
 474       xappName:
 475         type: string
 476         description: Name of the xApp
 477       namespace:
 478         type: string
 479         description: Name of the namespace
 480   ConfigValidationError:
 481     type: object
 482     required:
 483       - field
 484       - error
 485     properties:
 486       field:
 487         type: string
 488         description: Name of the parameter
 489       error:
 490         type: string
 491         description: Description of validation error
 492   ConfigValidationErrors:
 493     type: array
 494     items:
 495       $ref: '#/definitions/ConfigValidationError'
 496   XAppConfig:
 497     type: object
 498     required:
 499       - metadata
 500       - config
 501     properties:
 502       metadata:
 503         $ref: '#/definitions/ConfigMetadata'
 504       config:
 505         type: object
 506         description: Configuration in JSON format
 507   AllXappConfig:
 508     type: array
 509     items:
 510       $ref: '#/definitions/XAppConfig'
 511   EventType:
 512     type: string
 513     description: Event which is subscribed
 514     enum:
 515       - deployed
 516       - undeployed
 517       - created
 518       - modified
 519       - deleted
 520       - restarted
 521       - all
 522   SubscriptionData:
 523     type: object
 524     required:
 525       - targetUrl
 526       - eventType
 527       - maxRetries
 528       - retryTimer
 529     properties:
 530       targetUrl:
 531         type: string
 532         example: 'http://localhost:11111/apps/webhook/'
 533       eventType:
 534         $ref: '#/definitions/EventType'
 535       maxRetries:
 536         type: integer
 537         description: Maximum number of retries
 538       retryTimer:
 539         type: integer
 540         description: Time in seconds to wait before next retry
 541   subscriptionRequest:
 542     type: object
 543     required:
 544       - data
 545     properties:
 546       data:
 547         $ref: '#/definitions/SubscriptionData'
 548   subscriptionResponse:
 549     type: object
 550     properties:
 551       id:
 552         type: string
 553       version:
 554         type: integer
 555       eventType:
 556         $ref: '#/definitions/EventType'
 557   allSubscriptions:
 558     type: array
 559     items:
 560       $ref: '#/definitions/subscription'
 561   subscription:
 562     type: object
 563     properties:
 564       id:
 565         type: string
 566       data:
 567         $ref: '#/definitions/SubscriptionData'
 568   subscriptionNotification:
 569     type: object
 570     properties:
 571       id:
 572         type: string
 573       version:
 574         type: integer
 575       eventType:
 576         $ref: '#/definitions/EventType'
 577       xApps:
 578         $ref: '#/definitions/AllDeployedXapps'
 579   registerRequest:
 580     type: object
 581     required:
 582       - appName
 583       - appInstanceName
 584       - httpEndpoint
 585       - rmrEndpoint
 586     properties:
 587       appName:
 588         type: string
 589       appVersion:
 590         type: string
 591       configPath:
 592         type: string
 593       appInstanceName:
 594         type: string
 595       httpEndpoint:
 596         type: string
 597       rmrEndpoint:
 598         type: string
 599   deregisterRequest:
 600     type: object
 601     required:
 602       - appName
 603       - appInstanceName
 604     properties:
 605       appName:
 606         type: string
 607       appInstanceName:
 608         type: string