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