api/appmgr_rest_api.yaml

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