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