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             example: [ "da310eecdb8d44c2acc0ddaae01174b1","c748c58f8e0b438f9fd1f28370b17d47" ]
 370
 371   examples:
 372     dataSampleRequest:
 373       summary: Sample request
 374       description: Sample request body
 375       value:
 376         test:bookstore:
 377           bookstore-name: Chapters
 378           categories:
 379             - code: '01'
 380               name: SciFi
 381               books:
 382                 - authors:
 383                     - Iain M. Banks
 384                     - Ursula K. Le Guin
 385             - code: '02'
 386               name: kids
 387               books:
 388                 - authors:
 389                     - Philip Pullman
 390
 391     dataSamplePatchRequest:
 392       summary: Sample patch request
 393       description: Sample patch request body
 394       value:
 395         ietf-restconf:yang-patch:
 396           patch-id: patch-1
 397           edit:
 398             - edit-id: edit1
 399               operation: merge
 400               target: /
 401               value:
 402                 test:bookstore:
 403                   bookstore-name: Chapters
 404                   categories:
 405                     - code: '01'
 406                       name: Science
 407                       books:
 408                         - authors:
 409                             - Author1
 410                             - Author2
 411                     - code: '02'
 412                       name: Arts
 413                       books:
 414                         - authors:
 415                             - Author3
 416             - edit-id: edit2
 417               operation: merge
 418               target: /
 419               value:
 420                 test:bookstore:
 421                   bookstore-name: Novels
 422                   categories:
 423                     - code: '03'
 424                       name: History
 425                       books:
 426                         - authors:
 427                             - Iain M. Banks
 428                             - Ursula K. Le Guin
 429                     - code: '04'
 430                       name: Fiction
 431                       books:
 432                         - authors:
 433                             - Philip Pullman
 434
 435     dataSampleResponse:
 436       summary: Sample response
 437       description: Sample response for selecting 'sample 1'.
 438       value:
 439         bookstore:
 440           categories:
 441             - code: '01'
 442               books:
 443                 - authors:
 444                     - Iain M. Banks
 445                     - Ursula K. Le Guin
 446               name: SciFi
 447             - code: '02'
 448               books:
 449                 - authors:
 450                     - Philip Pullman
 451               name: kids
 452
 453     allCmHandleQueryParameters:
 454       value:
 455         cmHandleQueryParameters:
 456           - conditionName: hasAllModules
 457             conditionParameters:
 458               - { "moduleName": "my-module-1" }
 459               - { "moduleName": "my-module-2" }
 460               - { "moduleName": "my-module-3" }
 461           - conditionName: hasAllProperties
 462             conditionParameters:
 463               - { "Color": "yellow" }
 464               - { "Shape": "circle" }
 465               - { "Size": "small" }
 466           - conditionName: cmHandleWithCpsPath
 467             conditionParameters:
 468               - { "cpsPath": "//state[@cm-handle-state='ADVISED']" }
 469     pubPropCmHandleQueryParameters:
 470       value:
 471         cmHandleQueryParameters:
 472           - conditionName: hasAllProperties
 473             conditionParameters:
 474               - { "Color": "yellow" }
 475               - { "Shape": "circle" }
 476               - { "Size": "small" }
 477     modulesCmHandleQueryParameters:
 478       value:
 479         cmHandleQueryParameters:
 480           - conditionName: hasAllModules
 481             conditionParameters:
 482               - { "moduleName": "my-module-1" }
 483               - { "moduleName": "my-module-2" }
 484               - { "moduleName": "my-module-3" }
 485     cpsPathCmHandleStateQueryParameters:
 486       value:
 487         cmHandleQueryParameters:
 488           - conditionName: cmHandleWithCpsPath
 489             conditionParameters:
 490               - { "cpsPath": "//state[@cm-handle-state='LOCKED']" }
 491     cpsPathCmHandleDataSyncQueryParameters:
 492       value:
 493         cmHandleQueryParameters:
 494           - conditionName: cmHandleWithCpsPath
 495             conditionParameters:
 496               - { "cpsPath": "//state[@data-sync-enabled='true']" }
 497
 498   parameters:
 499     cmHandleInPath:
 500       name: cm-handle
 501       in: path
 502       description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
 503       required: true
 504       schema:
 505         type: string
 506         example: my-cm-handle
 507     moduleNameInQuery:
 508       name: module-name
 509       in: query
 510       description: Filter for a module name.This is an optional parameter
 511       required: false
 512       schema:
 513         type: string
 514         example: my-module
 515     revisionInQuery:
 516       name: revision
 517       in: query
 518       description: Filter for a module revision.This is an optional parameter and ignored when no module name is supplied
 519       required: false
 520       schema:
 521         type: string
 522         example: 2024-01-22
 523     dataSyncEnabled:
 524       name: dataSyncEnabled
 525       in: query
 526       description: Is used to enable or disable the data synchronization flag
 527       required: true
 528       schema:
 529         type: boolean
 530         example: true
 531     xpathInQuery:
 532       name: xpath
 533       in: query
 534       description: xpath
 535       required: false
 536       schema:
 537         type: string
 538         default: /
 539     requiredXpathInQuery:
 540       name: xpath
 541       in: query
 542       description: xpath
 543       required: true
 544       schema:
 545         type: string
 546     includeDescendantsOptionInQuery:
 547       name: include-descendants
 548       in: query
 549       description: Determines if descendants are included in response
 550       required: false
 551       schema:
 552         type: boolean
 553         default: false
 554     cpsPathInQuery:
 555       name: cps-path
 556       in: query
 557       description: For more details on cps path, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html
 558       required: false
 559       schema:
 560         type: string
 561         default: /
 562       examples:
 563         container cps path:
 564           value: //bookstore
 565         list attributes cps path:
 566           value: //categories[@code=1]
 567     dmiPluginIdentifierInQuery:
 568       name: dmi-plugin-identifier
 569       in: query
 570       description: dmi-plugin-identifier
 571       required: true
 572       schema:
 573         type: string
 574         example: my-dmi-plugin
 575     resourceIdentifierInQuery:
 576       name: resourceIdentifier
 577       in: query
 578       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.
 579       required: true
 580       allowReserved: true
 581       schema:
 582         type: string
 583       examples:
 584         sample 1:
 585           value:
 586             resourceIdentifier: \shops\bookstore
 587         sample 2:
 588           value:
 589             resourceIdentifier: \shops\bookstore\categories[@code=1]
 590         sample 3:
 591           value:
 592             resourceIdentifier: parent=shops,child=bookstore
 593     optionsParamInQuery:
 594       name: options
 595       in: query
 596       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.
 597       required: false
 598       schema:
 599         type: string
 600       allowReserved: true
 601       examples:
 602         sample 1:
 603           value:
 604             options: (depth=3)
 605         sample 2:
 606           value:
 607             options: (fields=book)
 608         sample 3:
 609           value:
 610             options: (depth=2,fields=book/authors)
 611     topicParamInQuery:
 612       name: topic
 613       in: query
 614       description: topic parameter in query.
 615       required: false
 616       schema:
 617         type: string
 618       allowReserved: true
 619       examples:
 620         sample 1:
 621           value:
 622             topic: my-topic-name
 623     requiredTopicParamInQuery:
 624       name: topic
 625       in: query
 626       description: mandatory topic parameter in query.
 627       required: true
 628       schema:
 629         type: string
 630       allowReserved: true
 631       examples:
 632         sample 1:
 633           value:
 634             topic: my-topic-name
 635     contentParamInHeader:
 636       name: Content-Type
 637       in: header
 638       required: false
 639       description: Content parameter for request, if content parameter is null, default value is application/json.
 640       schema:
 641         type: string
 642         default: application/json
 643         example: application/yang-data+json
 644     authorizationParamInHeader:
 645       name: Authorization
 646       in: header
 647       required: false
 648       description: Authorization parameter for request.
 649       schema:
 650         type: string
 651     datastoreName:
 652       name: datastore-name
 653       in: path
 654       description: The type of the requested data
 655       required: true
 656       schema:
 657         type: string
 658         example: ncmp-datastore:running
 659
 660   responses:
 661     NotFound:
 662       description: The specified resource was not found
 663       content:
 664         application/json:
 665           schema:
 666             $ref: '#/components/schemas/ErrorMessage'
 667           example:
 668             status: 400
 669             message: Not found error message
 670             details: Not found error details
 671     Unauthorized:
 672       description: Unauthorized
 673       content:
 674         application/json:
 675           schema:
 676             $ref: '#/components/schemas/ErrorMessage'
 677           example:
 678             status: 401
 679             message: Unauthorized error message
 680             details: Unauthorized error details
 681     Forbidden:
 682       description: Forbidden
 683       content:
 684         application/json:
 685           schema:
 686             $ref: '#/components/schemas/ErrorMessage'
 687           example:
 688             status: 403
 689             message: Forbidden error message
 690             details: Forbidden error details
 691     BadRequest:
 692       description: Bad Request
 693       content:
 694         application/json:
 695           schema:
 696             $ref: '#/components/schemas/ErrorMessage'
 697           example:
 698             status: 400 BAD_REQUEST
 699             message: Bad request error message
 700             details: Bad request error details
 701     Conflict:
 702       description: Conflict
 703       content:
 704         application/json:
 705           schema:
 706             $ref: '#/components/schemas/ErrorMessage'
 707           example:
 708             status: 409 CONFLICT
 709             message: Conflict error message
 710             details: Conflict error details
 711     NotImplemented:
 712       description: The given path has not been implemented
 713       content:
 714         application/json:
 715           schema:
 716             $ref: '#/components/schemas/ErrorMessage'
 717           example:
 718             status: 501
 719             message: Not implemented error message
 720             details: Not implemented error details
 721     Ok:
 722       description: OK
 723       content:
 724         application/json:
 725           schema:
 726             type: object
 727     Created:
 728       description: Created
 729       content: { }
 730     NoContent:
 731       description: No Content
 732       content: { }
 733     InternalServerError:
 734       description: Internal Server Error
 735       content:
 736         application/json:
 737           schema:
 738             $ref: "#/components/schemas/ErrorMessage"
 739           example:
 740             status: 500
 741             message: Internal Server Error
 742             details: Internal Server Error occurred
 743     BadGateway:
 744       description: Bad Gateway
 745       content:
 746         application/json:
 747           schema:
 748             $ref: "#/components/schemas/DmiErrorMessage"
 749           example:
 750             message: "Bad Gateway Error Message NCMP"
 751             dmi-response:
 752               http-code: 400
 753               body: "Bad Request"