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