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