cps-ncmp-rest/docs/openapi/components.yaml

   1 #  ============LICENSE_START=======================================================
   2 #  Copyright (C) 2021-2023 Nordix Foundation
   3 #  Modifications Copyright (C) 2021 Pantheon.tech
   4 #  Modifications Copyright (C) 2022 Bell Canada
   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 #  SPDX-License-Identifier: Apache-2.0
  19 #  ============LICENSE_END=========================================================
  20
  21 components:
  22   schemas:
  23     # Common Schemas
  24     ErrorMessage:
  25       type: object
  26       title: Error
  27       properties:
  28         status:
  29           type: string
  30         message:
  31           type: string
  32         details:
  33           type: string
  34     # DMI Server Exception Schema
  35     DmiErrorMessage:
  36       title: DMI Error Message
  37       type: object
  38       properties:
  39         message:
  40           type: string
  41           example: 'Bad Gateway Error Message NCMP'
  42         dmi-response:
  43           type: object
  44           properties:
  45             http-code:
  46               type: integer
  47               example: 400
  48             body:
  49               type: string
  50               example: Bad Request
  51     # Request Schemas
  52     RestDmiPluginRegistration:
  53       type: object
  54       properties:
  55         dmiPlugin:
  56           type: string
  57           example: my-dmi-plugin
  58           default: ""
  59         dmiDataPlugin:
  60           type: string
  61           example: my-dmi-data-plugin
  62           default: ""
  63         dmiModelPlugin:
  64           type: string
  65           example: my-dmi-model-plugin
  66           default: ""
  67         createdCmHandles:
  68           type: array
  69           items:
  70             $ref: '#/components/schemas/RestInputCmHandle'
  71         updatedCmHandles:
  72           type: array
  73           items:
  74             $ref: '#/components/schemas/RestInputCmHandle'
  75             example:
  76               cmHandle: my-cm-handle
  77               cmHandleProperties:
  78                 add-my-property: add-property
  79                 update-my-property: updated-property
  80                 delete-my-property: '~'
  81               publicCmHandleProperties:
  82                 add-my-property: add-property
  83                 update-my-property: updated-property
  84                 delete-my-property: '~'
  85         removedCmHandles:
  86           type: array
  87           items:
  88             type: string
  89           example: [ my-cm-handle1, my-cm-handle2, my-cm-handle3 ]
  90         upgradedCmHandles:
  91           $ref: '#/components/schemas/UpgradedCmHandles'
  92     DmiPluginRegistrationErrorResponse:
  93       type: object
  94       properties:
  95         failedCreatedCmHandles:
  96           type: array
  97           items:
  98             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
  99         failedUpdatedCmHandles:
 100           type: array
 101           items:
 102             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 103         failedRemovedCmHandles:
 104           type: array
 105           items:
 106             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 107         failedUpgradeCmHandles:
 108           type: array
 109           items:
 110             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 111     CmHandlerRegistrationErrorResponse:
 112       type: object
 113       properties:
 114         cmHandle:
 115           type: string
 116           example: my-cm-handle
 117         errorCode:
 118           type: string
 119           example: '00'
 120         errorText:
 121           type: string
 122           example: 'Unknown error. <error-details>'
 123
 124     RestInputCmHandle:
 125       required:
 126         - cmHandle
 127       type: object
 128       properties:
 129         cmHandle:
 130           type: string
 131           example: my-cm-handle
 132         cmHandleProperties:
 133           $ref: '#/components/schemas/RestCmHandleProperties'
 134         publicCmHandleProperties:
 135           $ref: '#/components/schemas/RestCmHandleProperties'
 136         moduleSetTag:
 137           type: string
 138           example: "my-module-set-tag"
 139         trustLevel:
 140             type: string
 141             enum: [COMPLETE, NONE]
 142             example: "COMPLETE"
 143         alternateId:
 144           type: string
 145           example: "my-alternate-id"
 146     RestCmHandleProperties:
 147       type: object
 148       additionalProperties:
 149         type: string
 150         example: my-property
 151     #Module upgrade schema
 152     UpgradedCmHandles:
 153       required:
 154         - cmHandles
 155       type: object
 156       properties:
 157         cmHandles:
 158           type: array
 159           items:
 160             type: string
 161           example: [ my-cm-handle1, my-cm-handle2, my-cm-handle3 ]
 162         moduleSetTag:
 163           type: string
 164           example: 'my-module-set-tag'
 165
 166     #Response Schemas
 167     RestModuleReference:
 168       type: object
 169       title: Module reference details
 170       properties:
 171         moduleName:
 172           type: string
 173           example: my-module-name
 174         revision:
 175           type: string
 176           example: my-module-revision
 177
 178     RestModuleDefinition:
 179       type: object
 180       title: Module definitions
 181       properties:
 182         moduleName:
 183           type: string
 184           example: my-module-name
 185         revision:
 186           type: string
 187           example: 2020-09-15
 188         content:
 189           type: string
 190           example: |
 191             module stores {
 192               yang-version 1.1;
 193               namespace 'org:onap:ccsdk:sample';
 194               prefix book-store;
 195               revision '2020-09-15' {
 196                 description
 197                 'Sample Model';
 198               }
 199             }
 200
 201     CmHandleQueryParameters:
 202       type: object
 203       title: Cm Handle query parameters for executing cm handle search
 204       properties:
 205         cmHandleQueryParameters:
 206           type: array
 207           items:
 208             $ref: '#/components/schemas/ConditionProperties'
 209         conditions:
 210           deprecated: true
 211           type: array
 212           items:
 213             $ref: '#/components/schemas/OldConditionProperties'
 214           description: not necessary, it is just for backward compatibility
 215
 216     ConditionProperties:
 217       properties:
 218         conditionName:
 219           type: string
 220         conditionParameters:
 221           type: array
 222           items:
 223             type: object
 224             additionalProperties:
 225               type: string
 226     OldConditionProperties:
 227       deprecated: true
 228       properties:
 229         name:
 230           type: string
 231         conditionParameters:
 232           type: array
 233           items:
 234             $ref: '#/components/schemas/ModuleNameAsJsonObject'
 235     ModuleNameAsJsonObject:
 236       properties:
 237         moduleName:
 238           type: string
 239           example: my-module
 240
 241     RestOutputCmHandle:
 242       type: object
 243       title: CM handle Details
 244       properties:
 245         cmHandle:
 246           type: string
 247           example: my-cm-handle1
 248         publicCmHandleProperties:
 249           $ref: '#/components/schemas/CmHandlePublicProperties'
 250         state:
 251           $ref: '#/components/schemas/CmHandleCompositeState'
 252         trustLevel:
 253           $ref: '#/components/schemas/CmHandleTrustLevel'
 254     CmHandlePublicProperties:
 255       type: object
 256       items:
 257         type: object
 258         additionalProperties:
 259           type: string
 260           example: 'Book Type'
 261     CmHandleCompositeState:
 262       type: object
 263       properties:
 264         cmHandleState:
 265           type: string
 266           example: ADVISED
 267         lockReason:
 268           $ref: '#/components/schemas/lock-reason'
 269         lastUpdateTime:
 270           type: string
 271           example: 2022-12-31T20:30:40.000+0000
 272         dataSyncEnabled:
 273           type: boolean
 274           example: false
 275         dataSyncState:
 276           $ref: '#/components/schemas/dataStores'
 277     CmHandleTrustLevel:
 278       type: string
 279       description: Current trust level of the relevant CM handle ID.
 280       example: COMPLETE
 281
 282     lock-reason:
 283       type: object
 284       properties:
 285         reason:
 286           type: string
 287           example: LOCKED_MISBEHAVING
 288         details:
 289           type: string
 290           example: locked due to failure in module sync
 291
 292     dataStores:
 293       type: object
 294       properties:
 295         operational:
 296           $ref: '#/components/schemas/sync-state'
 297         running:
 298           $ref: '#/components/schemas/sync-state'
 299
 300     sync-state:
 301       type: object
 302       properties:
 303         syncState:
 304           type: string
 305           example: NONE_REQUESTED
 306         lastSyncTime:
 307           type: string
 308           example: 2022-12-31T20:30:40.000+0000
 309
 310     RestOutputCmHandlePublicProperties:
 311       type: object
 312       properties:
 313         publicCmHandleProperties:
 314           $ref: '#/components/schemas/CmHandlePublicProperties'
 315
 316     RestOutputCmHandleCompositeState:
 317       type: object
 318       properties:
 319         state:
 320           $ref: '#/components/schemas/CmHandleCompositeState'
 321     # Data Operation Request Schemas
 322     DataOperationRequest:
 323       type: object
 324       title: execute data operation for given array of operations
 325       properties:
 326         operations:
 327           type: array
 328           items:
 329             $ref: '#/components/schemas/DataOperationDefinition'
 330           description: contains group of data operation requests
 331     DataOperationDefinition:
 332       required:
 333         - operation
 334         - datastore
 335         - operationId
 336       properties:
 337         operation:
 338           type: string
 339           example: 'read'
 340         operationId:
 341           type: string
 342           example: '12'
 343         datastore:
 344           type: string
 345           example: 'ncmp-datastore:passthrough-operational'
 346         options:
 347           type: string
 348           example: '(fields=schemas/schema)'
 349         resourceIdentifier:
 350           type: string
 351           example: 'parent/child'
 352         targetIds:
 353           type: array
 354           items:
 355             type: string
 356             example: [ "da310eecdb8d44c2acc0ddaae01174b1","c748c58f8e0b438f9fd1f28370b17d47" ]
 357
 358   examples:
 359     dataSampleRequest:
 360       summary: Sample request
 361       description: Sample request body
 362       value:
 363         test:bookstore:
 364           bookstore-name: Chapters
 365           categories:
 366             - code: '01'
 367               name: SciFi
 368               books:
 369                 - authors:
 370                     - Iain M. Banks
 371                     - Ursula K. Le Guin
 372             - code: '02'
 373               name: kids
 374               books:
 375                 - authors:
 376                     - Philip Pullman
 377
 378     dataSamplePatchRequest:
 379       summary: Sample patch request
 380       description: Sample patch request body
 381       value:
 382         ietf-restconf:yang-patch:
 383           patch-id: patch-1
 384           edit:
 385             - edit-id: edit1
 386               operation: merge
 387               target: /
 388               value:
 389                 test:bookstore:
 390                   bookstore-name: Chapters
 391                   categories:
 392                     - code: '01'
 393                       name: Science
 394                       books:
 395                         - authors:
 396                             - Author1
 397                             - Author2
 398                     - code: '02'
 399                       name: Arts
 400                       books:
 401                         - authors:
 402                             - Author3
 403             - edit-id: edit2
 404               operation: merge
 405               target: /
 406               value:
 407                 test:bookstore:
 408                   bookstore-name: Novels
 409                   categories:
 410                     - code: '03'
 411                       name: History
 412                       books:
 413                         - authors:
 414                             - Iain M. Banks
 415                             - Ursula K. Le Guin
 416                     - code: '04'
 417                       name: Fiction
 418                       books:
 419                         - authors:
 420                             - Philip Pullman
 421
 422     dataSampleResponse:
 423       summary: Sample response
 424       description: Sample response for selecting 'sample 1'.
 425       value:
 426         bookstore:
 427           categories:
 428             - code: '01'
 429               books:
 430                 - authors:
 431                     - Iain M. Banks
 432                     - Ursula K. Le Guin
 433               name: SciFi
 434             - code: '02'
 435               books:
 436                 - authors:
 437                     - Philip Pullman
 438               name: kids
 439
 440     allCmHandleQueryParameters:
 441       value:
 442         cmHandleQueryParameters:
 443           - conditionName: hasAllModules
 444             conditionParameters:
 445               - { "moduleName": "my-module-1" }
 446               - { "moduleName": "my-module-2" }
 447               - { "moduleName": "my-module-3" }
 448           - conditionName: hasAllProperties
 449             conditionParameters:
 450               - { "Color": "yellow" }
 451               - { "Shape": "circle" }
 452               - { "Size": "small" }
 453           - conditionName: cmHandleWithCpsPath
 454             conditionParameters:
 455               - { "cpsPath": "//state[@cm-handle-state='ADVISED']" }
 456     pubPropCmHandleQueryParameters:
 457       value:
 458         cmHandleQueryParameters:
 459           - conditionName: hasAllProperties
 460             conditionParameters:
 461               - { "Color": "yellow" }
 462               - { "Shape": "circle" }
 463               - { "Size": "small" }
 464     modulesCmHandleQueryParameters:
 465       value:
 466         cmHandleQueryParameters:
 467           - conditionName: hasAllModules
 468             conditionParameters:
 469               - { "moduleName": "my-module-1" }
 470               - { "moduleName": "my-module-2" }
 471               - { "moduleName": "my-module-3" }
 472     cpsPathCmHandleStateQueryParameters:
 473       value:
 474         cmHandleQueryParameters:
 475           - conditionName: cmHandleWithCpsPath
 476             conditionParameters:
 477               - { "cpsPath": "//state[@cm-handle-state='LOCKED']" }
 478     cpsPathCmHandleDataSyncQueryParameters:
 479       value:
 480         cmHandleQueryParameters:
 481           - conditionName: cmHandleWithCpsPath
 482             conditionParameters:
 483               - { "cpsPath": "//state[@data-sync-enabled='true']" }
 484
 485   parameters:
 486     cmHandleInPath:
 487       name: cm-handle
 488       in: path
 489       description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
 490       required: true
 491       schema:
 492         type: string
 493         example: my-cm-handle
 494     dataSyncEnabled:
 495       name: dataSyncEnabled
 496       in: query
 497       description: Is used to enable or disable the data synchronization flag
 498       required: true
 499       schema:
 500         type: boolean
 501         example: true
 502     xpathInQuery:
 503       name: xpath
 504       in: query
 505       description: xpath
 506       required: false
 507       schema:
 508         type: string
 509         default: /
 510     requiredXpathInQuery:
 511       name: xpath
 512       in: query
 513       description: xpath
 514       required: true
 515       schema:
 516         type: string
 517     includeDescendantsOptionInQuery:
 518       name: include-descendants
 519       in: query
 520       description: Determines if descendants are included in response
 521       required: false
 522       schema:
 523         type: boolean
 524         default: false
 525     cpsPathInQuery:
 526       name: cps-path
 527       in: query
 528       description: For more details on cps path, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html
 529       required: false
 530       schema:
 531         type: string
 532         default: /
 533       examples:
 534         container cps path:
 535           value: //bookstore
 536         list attributes cps path:
 537           value: //categories[@code=1]
 538     dmiPluginIdentifierInQuery:
 539       name: dmi-plugin-identifier
 540       in: query
 541       description: dmi-plugin-identifier
 542       required: true
 543       schema:
 544         type: string
 545         example: my-dmi-plugin
 546     resourceIdentifierInQuery:
 547       name: resourceIdentifier
 548       in: query
 549       description: The format of resource identifier depend on the associated DMI Plugin implementation. For ONAP DMI Plugin it will be RESTConf paths but it can really be anything.
 550       required: true
 551       allowReserved: true
 552       schema:
 553         type: string
 554       examples:
 555         sample 1:
 556           value:
 557             resourceIdentifier: \shops\bookstore
 558         sample 2:
 559           value:
 560             resourceIdentifier: \shops\bookstore\categories[@code=1]
 561         sample 3:
 562           value:
 563             resourceIdentifier: parent=shops,child=bookstore
 564     optionsParamInQuery:
 565       name: options
 566       in: query
 567       description: options parameter in query, it is mandatory to wrap key(s)=value(s) in parenthesis'()'. The format of options parameter depend on the associated DMI Plugin implementation.
 568       required: false
 569       schema:
 570         type: string
 571       allowReserved: true
 572       examples:
 573         sample 1:
 574           value:
 575             options: (depth=3)
 576         sample 2:
 577           value:
 578             options: (fields=book)
 579         sample 3:
 580           value:
 581             options: (depth=2,fields=book/authors)
 582     topicParamInQuery:
 583       name: topic
 584       in: query
 585       description: topic parameter in query.
 586       required: false
 587       schema:
 588         type: string
 589       allowReserved: true
 590       examples:
 591         sample 1:
 592           value:
 593             topic: my-topic-name
 594     requiredTopicParamInQuery:
 595       name: topic
 596       in: query
 597       description: mandatory topic parameter in query.
 598       required: true
 599       schema:
 600         type: string
 601       allowReserved: true
 602       examples:
 603         sample 1:
 604           value:
 605             topic: my-topic-name
 606     contentParamInHeader:
 607       name: Content-Type
 608       in: header
 609       required: false
 610       description: Content parameter for request, if content parameter is null, default value is application/json.
 611       schema:
 612         type: string
 613         default: application/json
 614         example: application/yang-data+json
 615     datastoreName:
 616       name: datastore-name
 617       in: path
 618       description: The type of the requested data
 619       required: true
 620       schema:
 621         type: string
 622         example: ncmp-datastore:running
 623
 624   responses:
 625     NotFound:
 626       description: The specified resource was not found
 627       content:
 628         application/json:
 629           schema:
 630             $ref: '#/components/schemas/ErrorMessage'
 631           example:
 632             status: 400
 633             message: Not found error message
 634             details: Not found error details
 635     Unauthorized:
 636       description: Unauthorized
 637       content:
 638         application/json:
 639           schema:
 640             $ref: '#/components/schemas/ErrorMessage'
 641           example:
 642             status: 401
 643             message: Unauthorized error message
 644             details: Unauthorized error details
 645     Forbidden:
 646       description: Forbidden
 647       content:
 648         application/json:
 649           schema:
 650             $ref: '#/components/schemas/ErrorMessage'
 651           example:
 652             status: 403
 653             message: Forbidden error message
 654             details: Forbidden error details
 655     BadRequest:
 656       description: Bad Request
 657       content:
 658         application/json:
 659           schema:
 660             $ref: '#/components/schemas/ErrorMessage'
 661           example:
 662             status: 400 BAD_REQUEST
 663             message: Bad request error message
 664             details: Bad request error details
 665     Conflict:
 666       description: Conflict
 667       content:
 668         application/json:
 669           schema:
 670             $ref: '#/components/schemas/ErrorMessage'
 671           example:
 672             status: 409 CONFLICT
 673             message: Conflict error message
 674             details: Conflict error details
 675     NotImplemented:
 676       description: The given path has not been implemented
 677       content:
 678         application/json:
 679           schema:
 680             $ref: '#/components/schemas/ErrorMessage'
 681           example:
 682             status: 501
 683             message: Not implemented error message
 684             details: Not implemented error details
 685     Ok:
 686       description: OK
 687       content:
 688         application/json:
 689           schema:
 690             type: object
 691     Created:
 692       description: Created
 693       content: { }
 694     NoContent:
 695       description: No Content
 696       content: { }
 697     InternalServerError:
 698       description: Internal Server Error
 699       content:
 700         application/json:
 701           schema:
 702             $ref: "#/components/schemas/ErrorMessage"
 703           example:
 704             status: 500
 705             message: Internal Server Error
 706             details: Internal Server Error occurred
 707     BadGateway:
 708       description: Bad Gateway
 709       content:
 710         application/json:
 711           schema:
 712             $ref: "#/components/schemas/DmiErrorMessage"
 713           example:
 714             message: "Bad Gateway Error Message NCMP"
 715             dmi-response:
 716               http-code: 400
 717               body: "Bad Request"