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

   1 #  ============LICENSE_START=======================================================
   2 #  Copyright (C) 2021-2022 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
 172     CmHandleQueryParameters:
 173       type: object
 174       title: Cm Handle query parameters for executing cm handle search
 175       properties:
 176         cmHandleQueryParameters:
 177           type: array
 178           items:
 179             type: object
 180             $ref: '#/components/schemas/ConditionProperties'
 181         conditions:
 182           deprecated: true
 183           type: array
 184           items:
 185             type: object
 186             $ref: '#/components/schemas/OldConditionProperties'
 187           description: not necessary, it is just for backward compatibility
 188       example:
 189         cmHandleQueryParameters:
 190           - conditionName: hasAllModules
 191             conditionParameters:
 192               - { "moduleName": "my-module-1" }
 193               - { "moduleName": "my-module-2" }
 194               - { "moduleName": "my-module-3" }
 195           - conditionName: hasAllProperties
 196             conditionParameters:
 197               - { "Color": "yellow" }
 198               - { "Shape": "circle" }
 199               - { "Size": "small" }
 200     ConditionProperties:
 201       properties:
 202         conditionName:
 203           type: string
 204         conditionParameters:
 205           type: array
 206           items:
 207             type: object
 208             additionalProperties:
 209               type: string
 210     OldConditionProperties:
 211       deprecated: true
 212       properties:
 213         name:
 214           type: string
 215         conditionParameters:
 216           type: array
 217           items:
 218             type: object
 219             $ref: '#/components/schemas/ModuleNameAsJsonObject'
 220     ModuleNameAsJsonObject:
 221       properties:
 222         moduleName:
 223           type: string
 224           example: my-module
 225
 226     RestOutputCmHandle:
 227       type: object
 228       title: CM handle Details
 229       properties:
 230         cmHandle:
 231           type: string
 232           example: my-cm-handle1
 233         publicCmHandleProperties:
 234           $ref: '#/components/schemas/CmHandlePublicProperties'
 235         state:
 236           $ref: '#/components/schemas/CmHandleCompositeState'
 237     CmHandlePublicProperties:
 238       type: array
 239       items:
 240         type: object
 241         additionalProperties:
 242           type: string
 243           example: Book Type
 244     CmHandleCompositeState:
 245       type: object
 246       properties:
 247         cmHandleState:
 248           type: string
 249           example: ADVISED
 250         lockReason:
 251           $ref: '#/components/schemas/lock-reason'
 252         lastUpdateTime:
 253           type: string
 254           example: 2022-12-31T20:30:40.000+0000
 255         dataSyncEnabled:
 256           type: boolean
 257           example: false
 258         dataSyncState:
 259           $ref: '#/components/schemas/dataStores'
 260
 261     lock-reason:
 262       type: object
 263       properties:
 264         reason:
 265           type: string
 266           example: LOCKED_MISBEHAVING
 267         details:
 268           type: string
 269           example: locked due to failure in module sync
 270
 271     dataStores:
 272       type: object
 273       properties:
 274         operational:
 275           $ref: '#/components/schemas/sync-state'
 276         running:
 277           $ref: '#/components/schemas/sync-state'
 278
 279     sync-state:
 280       type: object
 281       properties:
 282         state:
 283           type: string
 284           example: NONE_REQUESTED
 285         lastSyncTime:
 286           type: string
 287           example: 2022-12-31T20:30:40.000+0000
 288
 289     RestOutputCmHandlePublicProperties:
 290       type: object
 291       properties:
 292         publicCmHandleProperties:
 293           $ref: '#/components/schemas/CmHandlePublicProperties'
 294
 295     RestOutputCmHandleCompositeState:
 296       type: object
 297       properties:
 298         state:
 299           $ref: '#/components/schemas/CmHandleCompositeState'
 300
 301   examples:
 302     dataSampleRequest:
 303         summary: Sample request
 304         description: Sample request body
 305         value:
 306           test:bookstore:
 307             bookstore-name: Chapters
 308             categories:
 309               - code: '01'
 310                 name: SciFi
 311                 books:
 312                 - authors:
 313                     - Iain M. Banks
 314                     - Ursula K. Le Guin
 315               - code: '02'
 316                 name: kids
 317                 books:
 318                 - authors:
 319                     - Philip Pullman
 320
 321     dataSamplePatchRequest:
 322       summary: Sample patch request
 323       description: Sample patch request body
 324       value:
 325         ietf-restconf:yang-patch:
 326           patch-id: patch-1
 327           edit:
 328             - edit-id: edit1
 329               operation: merge
 330               target: /
 331               value:
 332                 test:bookstore:
 333                   bookstore-name: Chapters
 334                   categories:
 335                     - code: '01'
 336                       name: Science
 337                       books:
 338                         - authors:
 339                             - Author1
 340                             - Author2
 341                     - code: '02'
 342                       name: Arts
 343                       books:
 344                         - authors:
 345                             - Author3
 346             - edit-id: edit2
 347               operation: merge
 348               target: /
 349               value:
 350                 test:bookstore:
 351                   bookstore-name: Novels
 352                   categories:
 353                     - code: '03'
 354                       name: History
 355                       books:
 356                         - authors:
 357                             - Iain M. Banks
 358                             - Ursula K. Le Guin
 359                     - code: '04'
 360                       name: Fiction
 361                       books:
 362                         - authors:
 363                             - Philip Pullman
 364
 365     dataSampleResponse:
 366         summary: Sample response
 367         description: Sample response for selecting 'sample 1'.
 368         value:
 369           bookstore:
 370             categories:
 371               - code: '01'
 372                 books:
 373                   - authors:
 374                       - Iain M. Banks
 375                       - Ursula K. Le Guin
 376                 name: SciFi
 377               - code: '02'
 378                 books:
 379                   - authors:
 380                       - Philip Pullman
 381                 name: kids
 382
 383   parameters:
 384     cmHandleInPath:
 385       name: cm-handle
 386       in: path
 387       description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
 388       required: true
 389       schema:
 390         type: string
 391         example: my-cm-handle
 392     dataSyncEnabled:
 393       name: dataSyncEnabled
 394       in: query
 395       description: Is used to enable or disable the data synchronization flag
 396       required: true
 397       schema:
 398         type: boolean
 399         example: true
 400     xpathInQuery:
 401       name: xpath
 402       in: query
 403       description: xpath
 404       required: false
 405       schema:
 406         type: string
 407         default: /
 408     requiredXpathInQuery:
 409       name: xpath
 410       in: query
 411       description: xpath
 412       required: true
 413       schema:
 414         type: string
 415     includeDescendantsOptionInQuery:
 416       name: include-descendants
 417       in: query
 418       description: include-descendants
 419       required: false
 420       schema:
 421         type: boolean
 422         default: false
 423     cpsPathInQuery:
 424       name: cps-path
 425       in: query
 426       description: cps-path
 427       required: false
 428       schema:
 429         type: string
 430         default: /
 431     resourceIdentifierInQuery:
 432       name: resourceIdentifier
 433       in: query
 434       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.
 435       required: true
 436       allowReserved: true
 437       schema:
 438         type: string
 439       examples:
 440         sample 1:
 441           value:
 442             resourceIdentifier: \shops\bookstore
 443         sample 2:
 444           value:
 445             resourceIdentifier: \shops\bookstore\categories[@code=1]
 446         sample 3:
 447           value:
 448             resourceIdentifier: parent=shops,child=bookstore
 449     optionsParamInQuery:
 450       name: options
 451       in: query
 452       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.
 453       required: false
 454       schema:
 455         type: string
 456       allowReserved: true
 457       examples:
 458         sample 1:
 459           value:
 460             options: (depth=3)
 461         sample 2:
 462           value:
 463             options: (fields=book)
 464         sample 3:
 465           value:
 466             options: (depth=2,fields=book/authors)
 467     topicParamInQuery:
 468       name: topic
 469       in: query
 470       description: topic parameter in query.
 471       required: false
 472       schema:
 473         type: string
 474       allowReserved: true
 475       examples:
 476         sample 1:
 477           value:
 478             topic: my-topic-name
 479     contentParamInHeader:
 480       name: Content-Type
 481       in: header
 482       required: false
 483       description: Content parameter for request, if content parameter is null, default value is application/json.
 484       schema:
 485         type: string
 486         default: application/json
 487         example: application/yang-data+json
 488
 489   responses:
 490     NotFound:
 491       description: The specified resource was not found
 492       content:
 493         application/json:
 494           schema:
 495             $ref: '#/components/schemas/ErrorMessage'
 496           example:
 497             status: 400
 498             message: Not found error message
 499             details: Not found error details
 500     Unauthorized:
 501       description: Unauthorized
 502       content:
 503         application/json:
 504           schema:
 505             $ref: '#/components/schemas/ErrorMessage'
 506           example:
 507             status: 401
 508             message: Unauthorized error message
 509             details: Unauthorized error details
 510     Forbidden:
 511       description: Forbidden
 512       content:
 513         application/json:
 514           schema:
 515             $ref: '#/components/schemas/ErrorMessage'
 516           example:
 517            status: 403
 518            message: Forbidden error message
 519            details: Forbidden error details
 520     BadRequest:
 521       description: Bad Request
 522       content:
 523         application/json:
 524           schema:
 525             $ref: '#/components/schemas/ErrorMessage'
 526           example:
 527            status: 400 BAD_REQUEST
 528            message: Bad request error message
 529            details: Bad request error details
 530     Conflict:
 531       description: Conflict
 532       content:
 533         application/json:
 534           schema:
 535             $ref: '#/components/schemas/ErrorMessage'
 536           example:
 537            status: 409 CONFLICT
 538            message: Conflict error message
 539            details: Conflict error details
 540     NotImplemented:
 541       description: The given path has not been implemented
 542       content:
 543         application/json:
 544           schema:
 545             $ref: '#/components/schemas/ErrorMessage'
 546           example:
 547            status: 501
 548            message: Not implemented error message
 549            details: Not implemented error details
 550     Ok:
 551       description: OK
 552       content:
 553         application/json:
 554           schema:
 555             type: object
 556     Created:
 557       description: Created
 558       content: {}
 559     NoContent:
 560       description: No Content
 561       content: {}
 562     InternalServerError:
 563       description: Internal Server Error
 564       content:
 565         application/json:
 566           schema:
 567             $ref: "#/components/schemas/ErrorMessage"
 568           example:
 569             status: 500
 570             message: Internal Server Error
 571             details: Internal Server Error occurred
 572     BadGateway:
 573       description: Bad Gateway
 574       content:
 575         application/json:
 576           schema:
 577             $ref: "#/components/schemas/DmiErrorMessage"
 578           example:
 579             message: "Bad Gateway Error Message NCMP"
 580             dmi-response:
 581               http-code: 400
 582               body: "Bad Request"