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

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