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