docs/offeredapis/api_serviceCatalog/swagger.yaml

   1 #    Copyright (c) 2018 Orange
   2 #
   3 #    Licensed under the Apache License, Version 2.0 (the "License");
   4 #    you may not use this file except in compliance with the License.
   5 #    You may obtain a copy of the License at
   6 #
   7 #        http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 #    Unless required by applicable law or agreed to in writing, software
  10 #    distributed under the License is distributed on an "AS IS" BASIS,
  11 #    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 #    See the License for the specific language governing permissions and
  13 #    limitations under the License.swagger: "2.0"
  14 swagger: "2.0"
  15 info:
  16   description: "ServiceCatalog API to retrieve Service Specifications that are available from ONAP.\nThis API is\
  17     \ build from TMF open API17.5. \nOnly operation GET (by id & byList) for resource\
  18     \ serviceSpecification is available\n \
  19     \ To view this swagger file import it into https://editor.swagger.io/ \n"
  20   version: "4.1.0"
  21   title: "ServiceCatalog API"
  22   contact:
  23     name: "ONAP"
  24     url: "https://onap.readthedocs.io"
  25     email: "onap-discuss@lists.onap.org"
  26   license:
  27     name: "Apache 2.0"
  28     url: "http://www.apache.org/licenses/LICENSE-2.0"
  29   x-planned-retirement-date: "205001"
  30   x-component: "NBI"
  31   x-logo:
  32     url: "/redoc/logo.png"
  33     backgroundColor: "#FFFFFF"
  34 host: "serverRoot:30274"
  35 basePath: "/nbi/api/v4"
  36 schemes:
  37 - "http"
  38 - "https"
  39 produces:
  40 - "application/json;charset=utf-8"
  41 tags:
  42 - name: "ServiceSpecification"
  43   description: ""
  44 paths:
  45   x-interface:
  46     api-version: "4.1.0"
  47     last-mod-release: "Frankfurt"
  48   /serviceSpecification:
  49     get:
  50       tags:
  51       - "ServiceSpecification"
  52       produces:
  53       - "application/json;charset=utf-8"
  54       operationId: "serviceSpecification_Find"
  55       summary: "List service specifications"
  56       description: "This operation returns service specifications from a catalog.\n\
  57         Only a predefined set of attribute is proposed : Based on SDC limitations,\
  58         \ only attributes category and distributionStatus are available for serviceSpecification\
  59         \ filtering\nFields attribute could be used to filter attributes retrieved"
  60       deprecated: false
  61       parameters:
  62       - name: "fields"
  63         required: false
  64         in: "query"
  65         description: "Field selection - used to filtering the attributes to be retreived"
  66         type: "string"
  67       - name: "category"
  68         required: false
  69         in: "query"
  70         description: "Service Category (filter)"
  71         type: "string"
  72       - name: "distributionStatus"
  73         required: false
  74         in: "query"
  75         description: "Service distribution status (filter)"
  76         type: "string"
  77       responses:
  78         "200":
  79           description: "Ok"
  80           schema:
  81             type: "array"
  82             items:
  83               $ref: "#/definitions/ServiceSpecification"
  84         "400":
  85           description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
  86             \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
  87             \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
  88             \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
  89             \ parameter value"
  90           schema:
  91             $ref: "#/definitions/ErrorRepresentation"
  92         "401":
  93           description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
  94             \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
  95           schema:
  96             $ref: "#/definitions/ErrorRepresentation"
  97         "403":
  98           description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
  99             \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
 100             \ requests"
 101           schema:
 102             $ref: "#/definitions/ErrorRepresentation"
 103         "404":
 104           description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
 105             \ not found"
 106           schema:
 107             $ref: "#/definitions/ErrorRepresentation"
 108         "422":
 109           description: "Unprocessable entity\n\nFunctional error"
 110           schema:
 111             $ref: "#/definitions/ErrorRepresentation"
 112         "500":
 113           description: "Internal Server Error\n\nList of supported error codes:\n\
 114             - 1: Internal error"
 115           schema:
 116             $ref: "#/definitions/ErrorRepresentation"
 117         "503":
 118           description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
 119             \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
 120             \ retry later !"
 121           schema:
 122             $ref: "#/definitions/ErrorRepresentation"
 123   /serviceSpecification/{id}:
 124     get:
 125       tags:
 126       - "ServiceSpecification"
 127       produces:
 128       - "application/json;charset=utf-8"
 129       operationId: "serviceSpecification_Get"
 130       summary: "Retrieve a service specification"
 131       description: "This operation returns a service specification by its id from\
 132         \ a catalog. Attribute selection is enabled using the fields attribute."
 133       deprecated: false
 134       parameters:
 135       - name: "id"
 136         required: true
 137         in: "path"
 138         description: "The Id of the ServiceSpecification"
 139         type: "string"
 140       - name: "fields"
 141         required: false
 142         in: "query"
 143         description: "Attribute selection"
 144         type: "string"
 145       responses:
 146         "200":
 147           description: "Ok"
 148           schema:
 149             $ref: "#/definitions/ServiceSpecification"
 150         "400":
 151           description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
 152             \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
 153             \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
 154             \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
 155             \ parameter value"
 156           schema:
 157             $ref: "#/definitions/ErrorRepresentation"
 158         "401":
 159           description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
 160             \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
 161           schema:
 162             $ref: "#/definitions/ErrorRepresentation"
 163         "403":
 164           description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
 165             \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
 166             \ requests"
 167           schema:
 168             $ref: "#/definitions/ErrorRepresentation"
 169         "404":
 170           description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
 171             \ not found"
 172           schema:
 173             $ref: "#/definitions/ErrorRepresentation"
 174         "422":
 175           description: "Unprocessable entity\n\nFunctional error"
 176           schema:
 177             $ref: "#/definitions/ErrorRepresentation"
 178         "500":
 179           description: "Internal Server Error\n\nList of supported error codes:\n\
 180             - 1: Internal error"
 181           schema:
 182             $ref: "#/definitions/ErrorRepresentation"
 183         "503":
 184           description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
 185             \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
 186             \ retry later !"
 187           schema:
 188             $ref: "#/definitions/ErrorRepresentation"
 189   /serviceSpecification/{id}/specificationInputSchema:
 190     get:
 191       tags:
 192       - "ServiceSpecification"
 193       produces:
 194       - "application/json;charset=utf-8"
 195       operationId: "specificationInputSchemaGet"
 196       summary: "Retrieve a service specification Input Schema"
 197       description: "This operation returns a service specification Input schema by its id from\
 198         \ a catalog. Attribute selection is enabled using the fields attribute."
 199       deprecated: false
 200       parameters:
 201       - name: "id"
 202         required: true
 203         in: "path"
 204         description: "The Id of the ServiceSpecification"
 205         type: "string"
 206       - name: "fields"
 207         required: false
 208         in: "query"
 209         description: "Attribute selection"
 210         type: "string"
 211       responses:
 212         "200":
 213           description: "Ok"
 214           schema:
 215             $ref: "#/definitions/SpecificationInputSchema"
 216         "400":
 217           description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
 218             \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
 219             \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
 220             \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
 221             \ parameter value"
 222           schema:
 223             $ref: "#/definitions/ErrorRepresentation"
 224         "401":
 225           description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
 226             \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
 227           schema:
 228             $ref: "#/definitions/ErrorRepresentation"
 229         "403":
 230           description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
 231             \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
 232             \ requests"
 233           schema:
 234             $ref: "#/definitions/ErrorRepresentation"
 235         "404":
 236           description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
 237             \ not found"
 238           schema:
 239             $ref: "#/definitions/ErrorRepresentation"
 240         "422":
 241           description: "Unprocessable entity\n\nFunctional error"
 242           schema:
 243             $ref: "#/definitions/ErrorRepresentation"
 244         "500":
 245           description: "Internal Server Error\n\nList of supported error codes:\n\
 246             - 1: Internal error"
 247           schema:
 248             $ref: "#/definitions/ErrorRepresentation"
 249         "503":
 250           description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
 251             \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
 252             \ retry later !"
 253           schema:
 254             $ref: "#/definitions/ErrorRepresentation"
 255
 256 definitions:
 257   LifecycleStatusValues:
 258     description: "Service lifecycle value from ONAP SDC"
 259     type: "string"
 260     enum:
 261     - "NOT_CERTIFIED_CHECKOUT"
 262     - "NOT_CERTIFIED_CHECKIN"
 263     - "READY_FOR_CERTIFICATION"
 264     - "CERTIFICATION_IN_PROGRESS"
 265     - "CERTIFIED"
 266   DistributionStatus:
 267     description: "Service distribution status from ONAP."
 268     type: "string"
 269     enum:
 270     - "DISTRIBUTION_NOT_APPROVED"
 271     - "DISTRIBUTION_APPROVED"
 272     - "DISTRIBUTED"
 273     - "DISTRIBUTION_REJECTED"
 274   ErrorRepresentation:
 275     description: "This class is used to describe error.\nfor nbi Beijing release we\
 276       \ do not manage additional error for serviceCatalog"
 277     required:
 278     - "code"
 279     - "reason"
 280     type: "object"
 281     properties:
 282       code:
 283         description: "Application related code (as defined in the API or from a common\
 284           \ list)"
 285         type: "integer"
 286         format: "int32"
 287       reason:
 288         description: "Text that explains the reason for error. This can be shown to\
 289           \ a client user."
 290         type: "string"
 291       message:
 292         description: "Text that provide more details and corrective actions related\
 293           \ to the error. This can be shown to a client user"
 294         type: "string"
 295       status:
 296         description: "http error code extension like 400-2"
 297         type: "string"
 298       referenceErrror:
 299         description: "url pointing to documentation describing the error"
 300         type: "string"
 301       '@type':
 302         description: "The class type of a REST resource."
 303         type: "string"
 304       '@schemaLocation':
 305         description: "it provides a link to the schema describing a REST resource."
 306         type: "string"
 307   TimePeriod:
 308     description: "A time period"
 309     type: "object"
 310     properties:
 311       startDateTime:
 312         description: "Start date and time of the period"
 313         type: "string"
 314         format: "date-time"
 315       endDateTime:
 316         description: "End date and time of the period"
 317         type: "string"
 318         format: "date-time"
 319   RelatedPartyRef:
 320     description: "Party linked to the service catalog.\nin nbi we retrieve information\
 321       \ about last updater of the service in SDC"
 322     type: "object"
 323     properties:
 324       id:
 325         description: "Unique identifier of the related party. Filled with lastUpdaterUserId"
 326         type: "string"
 327       role:
 328         description: "Role payed by the related party\nOnly role 'lastUpdater' is\
 329           \ retrieved in Beijing release"
 330         type: "string"
 331       name:
 332         description: "Name of the related party - Filled with lastUpdatedFullName"
 333         type: "string"
 334   ServiceSpecification:
 335     description: "ServiceSpecification is a class that offers characteristics to describe\
 336       \ a type of service. Functionally, it acts as a template by which Services may\
 337       \ be instantiated. By sharing the same specification, these services would therefore\
 338       \ share the same set of characteristics.\nthe service information are retrieved\
 339       \ in SDC"
 340     required:
 341     - "invariantUUID"
 342     type: "object"
 343     properties:
 344       id:
 345         description: "Unique identifier of the service specification. Filled with\
 346           \ SDC Service uuid"
 347         type: "string"
 348       href:
 349         description: "Reference of the service specification"
 350         type: "string"
 351       name:
 352         description: "Name of the service specification- Filled with SDC Service name"
 353         type: "string"
 354       description:
 355         description: "A narrative that explains in detail what the service specification\
 356           \ is - Filled with SDC Service description"
 357         type: "string"
 358       '@type':
 359         description: "This attribute allows to dynamically extends TMF class. Valued\
 360           \ with 'ONAPservice'. We used this features to add following attributes:\n\
 361           invariantUUID\ntoscaModelURL\ntoscaResourceName\ncategory (1)\nsubcategory\
 362           \ (1)\ndistributionStatus"
 363         type: "string"
 364         default: "ONAPservice"
 365       '@schemaLocation':
 366         description: "Not used"
 367         type: "string"
 368       '@baseType':
 369         description: "Not used"
 370         type: "string"
 371       invariantUUID:
 372         description: "Additional attribute (not in the TMF API) - extended through\
 373           \ @type - invariantUUID"
 374         type: "string"
 375       toscaModelURL:
 376         description: "Additional attribute (not in the TMF API) - extended through\
 377           \ @type - toscaModelURL"
 378         type: "string"
 379       toscaResourceName:
 380         description: "Additional attribute (not in the TMF API) - extended through\
 381           \ @type - toscaResourceName"
 382         type: "string"
 383       category:
 384         description: "Additional attribute - extended through @type - category\nPlease\
 385           \ note that this attribute is managed in TMF - in future release we'll introduce\
 386           \ category resource"
 387         type: "string"
 388       subcategory:
 389         description: "Additional attribute - extended through @type - category\nPlease\
 390           \ note that this attribute is managed in TMF - in future release we'll introduce\
 391           \ category resourc"
 392         type: "string"
 393       distributionStatus:
 394         $ref: "#/definitions/DistributionStatus"
 395       version:
 396         description: "Service specification version - Filled with SDC Service version"
 397         type: "string"
 398       lifecycleStatus:
 399         $ref: "#/definitions/LifecycleStatusValues"
 400       targetServiceSchema:
 401         $ref: "#/definitions/TargetServiceSchemaRef"
 402       attachment:
 403         type: "array"
 404         items:
 405           $ref: "#/definitions/Attachment"
 406       relatedParty:
 407         type: "array"
 408         items:
 409           $ref: "#/definitions/RelatedPartyRef"
 410       resourceSpecification:
 411         type: "array"
 412         items:
 413           $ref: "#/definitions/ResourceSpecificationRef"
 414       serviceSpecCharacteristic:
 415         type: "array"
 416         items:
 417           $ref: "#/definitions/ServiceSpecCharacteristic"
 418   ServiceSpecCharacteristic:
 419     description: "A characteristic quality or distinctive feature of a ServiceSpecification.\
 420       \ \nServiceSpecCharacteristic are retrieved in the serviceTosca file in the\
 421       \ topology_template section in the inputs section."
 422     type: "object"
 423     properties:
 424       name:
 425         description: "Name of the characteristic - Filled with parameter_name"
 426         type: "string"
 427       description:
 428         description: "A narrative that explains in detail what the characteristic\
 429           \ is - Filled with parameter_description"
 430         type: "string"
 431       valueType:
 432         description: "A kind of value that the characteristic can take on, from Dublin\
 433           \ from Dublin we use the object type to describe service characteristic values"
 434         type: "string"
 435       '@type':
 436         description: "This attribute allows to dynamically extends TMF class. Valued\
 437           \ with: 'ONAPserviceCharacteristic'. We do not used this feature in nbi"
 438         type: "string"
 439       '@schemaLocation':
 440         description: "An url pointing to type description - we do not use it"
 441         type: "string"
 442       required:
 443         description: "A parameter to define if the characteristic is mandatory - Filled\
 444           \ from parameter_required – if not fielded by default ‘true’"
 445         type: "boolean"
 446         default: true
 447       status:
 448         description: "Status of the characteristic - filled with status_value"
 449         type: "string"
 450       serviceSpecCharacteristicValue:
 451         type: "array"
 452         items:
 453           $ref: "#/definitions/ServiceSpecCharacteristicValue"
 454   Attachment:
 455     description: "An attachment is a file uses to describe the service.\nIn nbi we\
 456       \ use attachment to retrieve ONAP artifacts."
 457     type: "object"
 458     properties:
 459       id:
 460         description: "Unique identifier of the attachment - filled with artifactUUID."
 461         type: "string"
 462       name:
 463         description: "Name of the attachment - filled with artifactName"
 464         type: "string"
 465       description:
 466         description: "Description of the attachment - filled with artifactDescription"
 467         type: "string"
 468       '@type':
 469         description: "This attribute allows to dynamically extends TMF class. Valued\
 470           \ with 'ONAPartifact'. We used this features to add following attributes:\
 471           \ \nartifactLabel\nartifactGroupType\nartifactTimeout\nartifactChecksum\n\
 472           artifactVersion\ngeneratedFromUUID"
 473         type: "string"
 474         default: "ONAPartifact"
 475       artifactLabel:
 476         description: "Additional attribute (not in the TMF API) - extended through\
 477           \ @type - artifactLabel"
 478         type: "string"
 479       artifactGroupType:
 480         description: "Additional attribute (not in the TMF API) - extended through\
 481           \ @type - artifactGroupType"
 482         type: "string"
 483       artifactTimeout:
 484         description: "Additional attribute (not in the TMF API) - extended through\
 485           \ @type - artifactTimeout"
 486         type: "string"
 487       artifactChecksum:
 488         description: "Additional attribute (not in the TMF API) - extended through\
 489           \ @type - artifactChecksum"
 490         type: "string"
 491       artifactVersion:
 492         description: "Additional attribute (not in the TMF API) - extended through\
 493           \ @type - artifactVersion"
 494         type: "string"
 495       generatedFromUUID:
 496         description: "Additional attribute (not in the TMF API) - extended through\
 497           \ @type - generatedFromUUID"
 498         type: "string"
 499       url:
 500         description: "Uniform Resource Locator, is a web page address - filled with\
 501           \ artifactURL"
 502         type: "string"
 503       mimeType:
 504         description: "Filled with artifactType"
 505         type: "string"
 506   ServiceSpecCharacteristicValue:
 507     description: "A number or text that can be assigned to a service specification\
 508       \ characteristic.\nServiceSpecCharacteristicValue are retrieved in the service\
 509       \ Tosca file"
 510     type: "object"
 511     properties:
 512       '@type':
 513         description: "This attribute allows to dynamically extends TMF class. Valued\
 514           \ with: 'ServiceSpecName_ServiceCharacteristic'."
 515         type: "string"
 516       '@schemaLocation':
 517         description: "An url pointing to type description - we use it in nbi\
 518           \ for specifying the specificationInputSchema url"
 519         type: "string"
 520       valueType:
 521         description: "A kind of value that the characteristic can take on,\
 522           \ from Dublin release we use an object valueType to\
 523           \ group the Tosca Model Inputs, the object schema is described\
 524           \ by the specificationInputSchema url"
 525         type: "string"
 526   SpecificationInputSchema:
 527     description: "A json schema of the service specification input characteristics\
 528       \ \n. The Inputs in the schema files are obtained the service Tosca file Inputs"
 529     type: "object"
 530     properties:
 531       ServiceCharacteristics:
 532         $ref: "#/definitions/SchemaForServiceCharacteristics"
 533   SchemaForServiceCharacteristics:
 534     description: "The object describing the schema of the service specification input characteristics.\
 535       \ \n. The Inputs in the schema files are obtained the service Tosca file Inputs"
 536     type: "object"
 537     properties:
 538       required:
 539         description: "defines the parameter key names that are mandatory to send"
 540         type: "array"
 541         items:
 542           type: "string"
 543       properties:
 544         description: "defines all the input key names and types for the Service Instantiation"
 545         type: "object"
 546   ResourceSpecificationRef:
 547     description: "A list of resourceSpec identified to deliver the service.\nfor nbi\
 548       \ we retrieve resource information available in service description (through\
 549       \ SDC api) bu as well information retrieved in the TOSCA file."
 550     type: "object"
 551     properties:
 552       id:
 553         description: "Unique identifier of the resource specification - filled with\
 554           \ resourceUUID"
 555         type: "string"
 556       version:
 557         description: "Version for this resource specification - filled with resourceVersion"
 558         type: "string"
 559       name:
 560         description: "Name of the resource specification - filled with resourceName"
 561         type: "string"
 562       '@type':
 563         description: "This attribute allows to dynamically extends TMF class. Valued\
 564           \ with: 'ONAPresource'. We used this features to add following attributes:\n\
 565           resourceInstanceName\nresourceInvariantUUID\nresourceType\nmodelCustomizationName\n\
 566           modelCustomizationId"
 567         type: "string"
 568         default: "ONAPresource"
 569       resourceInstanceName:
 570         description: "Additional attribute (not in the TMF API) - extended through\
 571           \ @type - resourceInstanceName"
 572         type: "string"
 573       resourceInvariantUUID:
 574         description: "Additional attribute (not in the TMF API) - extended through\
 575           \ @type - resourceInvariantUUID"
 576         type: "string"
 577       resourceType:
 578         description: "Additional attribute (not in the TMF API) - extended through\
 579           \ @type - resoucreType"
 580         type: "string"
 581       modelCustomizationName:
 582         description: "Additional attribute (not in the TMF API) - extended through\
 583           \ @type - Retrieved in the TOSCA file : attribute name in topology_template/node_template\
 584           \ for the resource"
 585         type: "string"
 586       modelCustomizationId:
 587         description: "Additional attribute (not in the TMF API) - extended through\
 588           \ @type - Retrieved in the TOSCA file : attribute customizationUUID in topology_template/node_template\
 589           \ for the resource"
 590         type: "string"
 591   TargetServiceSchemaRef:
 592     description: "Target Service Schema"
 593     required:
 594     - "@type"
 595     - "@schemaLocation"
 596     type: "object"
 597     properties:
 598       '@type':
 599         description: ""
 600         type: "string"
 601       '@schemaLocation':
 602         description: ""
 603         type: "string"