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

   1 #  ============LICENSE_START=======================================================
   2 #  Copyright (C) 2021-2023 Nordix Foundation
   3 #  Modifications Copyright (C) 2021 Pantheon.tech
   4 #  Modifications Copyright (C) 2022 Bell Canada
   5 #  ================================================================================
   6 #  Licensed under the Apache License, Version 2.0 (the "License");
   7 #  you may not use this file except in compliance with the License.
   8 #  You may obtain a copy of the License at
   9 #
  10 #        http://www.apache.org/licenses/LICENSE-2.0
  11 #
  12 #  Unless required by applicable law or agreed to in writing, software
  13 #  distributed under the License is distributed on an "AS IS" BASIS,
  14 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15 #  See the License for the specific language governing permissions and
  16 #  limitations under the License.
  17 #
  18 #  SPDX-License-Identifier: Apache-2.0
  19 #  ============LICENSE_END=========================================================
  20
  21 components:
  22   schemas:
  23     # Common Schemas
  24     ErrorMessage:
  25       type: object
  26       title: Error
  27       properties:
  28         status:
  29           type: string
  30         message:
  31           type: string
  32         details:
  33           type: string
  34     # DMI Server Exception Schema
  35     DmiErrorMessage:
  36       title: DMI Error Message
  37       type: object
  38       properties:
  39         message:
  40           type: string
  41           example: 'Bad Gateway Error Message NCMP'
  42         dmi-response:
  43           type: object
  44           properties:
  45             http-code:
  46               type: integer
  47               example: 400
  48             body:
  49               type: string
  50               example: Bad Request
  51     # Request Schemas
  52     RestDmiPluginRegistration:
  53       type: object
  54       properties:
  55         dmiPlugin:
  56           type: string
  57           example: my-dmi-plugin
  58           default: ""
  59         dmiDataPlugin:
  60           type: string
  61           example: my-dmi-data-plugin
  62           default: ""
  63         dmiModelPlugin:
  64           type: string
  65           example: my-dmi-model-plugin
  66           default: ""
  67         createdCmHandles:
  68           type: array
  69           items:
  70             $ref: '#/components/schemas/RestInputCmHandle'
  71         updatedCmHandles:
  72           type: array
  73           items:
  74             $ref: '#/components/schemas/RestInputCmHandle'
  75             example:
  76               cmHandle: my-cm-handle
  77               cmHandleProperties:
  78                 add-my-property: add-property
  79                 update-my-property: updated-property
  80                 delete-my-property: '~'
  81               publicCmHandleProperties:
  82                 add-my-property: add-property
  83                 update-my-property: updated-property
  84                 delete-my-property: '~'
  85         removedCmHandles:
  86           type: array
  87           items:
  88             type: string
  89           example: [ my-cm-handle1, my-cm-handle2, my-cm-handle3 ]
  90         upgradedCmHandles:
  91           $ref: '#/components/schemas/UpgradedCmHandles'
  92     DmiPluginRegistrationErrorResponse:
  93       type: object
  94       properties:
  95         failedCreatedCmHandles:
  96           type: array
  97           items:
  98             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
  99         failedUpdatedCmHandles:
 100           type: array
 101           items:
 102             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 103         failedRemovedCmHandles:
 104           type: array
 105           items:
 106             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 107         failedUpgradeCmHandles:
 108           type: array
 109           items:
 110             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 111     CmHandlerRegistrationErrorResponse:
 112       type: object
 113       properties:
 114         cmHandle:
 115           type: string
 116           example: my-cm-handle
 117         errorCode:
 118           type: string
 119           example: '00'
 120         errorText:
 121           type: string
 122           example: 'Unknown error. <error-details>'
 123
 124     RestInputCmHandle:
 125       required:
 126         - cmHandle
 127       type: object
 128       properties:
 129         cmHandle:
 130           type: string
 131           example: my-cm-handle
 132         cmHandleProperties:
 133           $ref: '#/components/schemas/RestCmHandleProperties'
 134         publicCmHandleProperties:
 135           $ref: '#/components/schemas/RestCmHandleProperties'
 136         moduleSetTag:
 137           type: string
 138           example: "my-module-set-tag"
 139         trustLevel:
 140             type: string
 141             enum: [COMPLETE, NONE]
 142             example: "COMPLETE"
 143         alternateId:
 144           type: string
 145           example: "my-alternate-id"
 146     RestCmHandleProperties:
 147       type: object
 148       additionalProperties:
 149         type: string
 150         example: my-property
 151     #Module upgrade schema
 152     UpgradedCmHandles:
 153       required:
 154         - cmHandles
 155       type: object
 156       properties:
 157         cmHandles:
 158           type: array
 159           items:
 160             type: string
 161           example: [ my-cm-handle1, my-cm-handle2, my-cm-handle3 ]
 162         moduleSetTag:
 163           type: string
 164           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     dataSyncEnabled:
 496       name: dataSyncEnabled
 497       in: query
 498       description: Is used to enable or disable the data synchronization flag
 499       required: true
 500       schema:
 501         type: boolean
 502         example: true
 503     xpathInQuery:
 504       name: xpath
 505       in: query
 506       description: xpath
 507       required: false
 508       schema:
 509         type: string
 510         default: /
 511     requiredXpathInQuery:
 512       name: xpath
 513       in: query
 514       description: xpath
 515       required: true
 516       schema:
 517         type: string
 518     includeDescendantsOptionInQuery:
 519       name: include-descendants
 520       in: query
 521       description: Determines if descendants are included in response
 522       required: false
 523       schema:
 524         type: boolean
 525         default: false
 526     cpsPathInQuery:
 527       name: cps-path
 528       in: query
 529       description: For more details on cps path, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html
 530       required: false
 531       schema:
 532         type: string
 533         default: /
 534       examples:
 535         container cps path:
 536           value: //bookstore
 537         list attributes cps path:
 538           value: //categories[@code=1]
 539     dmiPluginIdentifierInQuery:
 540       name: dmi-plugin-identifier
 541       in: query
 542       description: dmi-plugin-identifier
 543       required: true
 544       schema:
 545         type: string
 546         example: my-dmi-plugin
 547     resourceIdentifierInQuery:
 548       name: resourceIdentifier
 549       in: query
 550       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.
 551       required: true
 552       allowReserved: true
 553       schema:
 554         type: string
 555       examples:
 556         sample 1:
 557           value:
 558             resourceIdentifier: \shops\bookstore
 559         sample 2:
 560           value:
 561             resourceIdentifier: \shops\bookstore\categories[@code=1]
 562         sample 3:
 563           value:
 564             resourceIdentifier: parent=shops,child=bookstore
 565     optionsParamInQuery:
 566       name: options
 567       in: query
 568       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.
 569       required: false
 570       schema:
 571         type: string
 572       allowReserved: true
 573       examples:
 574         sample 1:
 575           value:
 576             options: (depth=3)
 577         sample 2:
 578           value:
 579             options: (fields=book)
 580         sample 3:
 581           value:
 582             options: (depth=2,fields=book/authors)
 583     topicParamInQuery:
 584       name: topic
 585       in: query
 586       description: topic parameter in query.
 587       required: false
 588       schema:
 589         type: string
 590       allowReserved: true
 591       examples:
 592         sample 1:
 593           value:
 594             topic: my-topic-name
 595     requiredTopicParamInQuery:
 596       name: topic
 597       in: query
 598       description: mandatory topic parameter in query.
 599       required: true
 600       schema:
 601         type: string
 602       allowReserved: true
 603       examples:
 604         sample 1:
 605           value:
 606             topic: my-topic-name
 607     contentParamInHeader:
 608       name: Content-Type
 609       in: header
 610       required: false
 611       description: Content parameter for request, if content parameter is null, default value is application/json.
 612       schema:
 613         type: string
 614         default: application/json
 615         example: application/yang-data+json
 616     datastoreName:
 617       name: datastore-name
 618       in: path
 619       description: The type of the requested data
 620       required: true
 621       schema:
 622         type: string
 623         example: ncmp-datastore:running
 624
 625   responses:
 626     NotFound:
 627       description: The specified resource was not found
 628       content:
 629         application/json:
 630           schema:
 631             $ref: '#/components/schemas/ErrorMessage'
 632           example:
 633             status: 400
 634             message: Not found error message
 635             details: Not found error details
 636     Unauthorized:
 637       description: Unauthorized
 638       content:
 639         application/json:
 640           schema:
 641             $ref: '#/components/schemas/ErrorMessage'
 642           example:
 643             status: 401
 644             message: Unauthorized error message
 645             details: Unauthorized error details
 646     Forbidden:
 647       description: Forbidden
 648       content:
 649         application/json:
 650           schema:
 651             $ref: '#/components/schemas/ErrorMessage'
 652           example:
 653             status: 403
 654             message: Forbidden error message
 655             details: Forbidden error details
 656     BadRequest:
 657       description: Bad Request
 658       content:
 659         application/json:
 660           schema:
 661             $ref: '#/components/schemas/ErrorMessage'
 662           example:
 663             status: 400 BAD_REQUEST
 664             message: Bad request error message
 665             details: Bad request error details
 666     Conflict:
 667       description: Conflict
 668       content:
 669         application/json:
 670           schema:
 671             $ref: '#/components/schemas/ErrorMessage'
 672           example:
 673             status: 409 CONFLICT
 674             message: Conflict error message
 675             details: Conflict error details
 676     NotImplemented:
 677       description: The given path has not been implemented
 678       content:
 679         application/json:
 680           schema:
 681             $ref: '#/components/schemas/ErrorMessage'
 682           example:
 683             status: 501
 684             message: Not implemented error message
 685             details: Not implemented error details
 686     Ok:
 687       description: OK
 688       content:
 689         application/json:
 690           schema:
 691             type: object
 692     Created:
 693       description: Created
 694       content: { }
 695     NoContent:
 696       description: No Content
 697       content: { }
 698     InternalServerError:
 699       description: Internal Server Error
 700       content:
 701         application/json:
 702           schema:
 703             $ref: "#/components/schemas/ErrorMessage"
 704           example:
 705             status: 500
 706             message: Internal Server Error
 707             details: Internal Server Error occurred
 708     BadGateway:
 709       description: Bad Gateway
 710       content:
 711         application/json:
 712           schema:
 713             $ref: "#/components/schemas/DmiErrorMessage"
 714           example:
 715             message: "Bad Gateway Error Message NCMP"
 716             dmi-response:
 717               http-code: 400
 718               body: "Bad Request"