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