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 designed for ONAP Beijing Release.\nThis API is\
  17     \ build from TMF open API17.5. \nOnly operation GET (by id & byList) for resource\
  18     \ serviceSpecification is available\n\n"
  19   version: "4.0.1"
  20   title: "API ServiceCatalog"
  21   x-logo:
  22     url: "/redoc/logo.png"
  23     backgroundColor: "#FFFFFF"
  24 host: "serverRoot"
  25 basePath: "/nbi/api/v1"
  26 schemes:
  27 - "https"
  28 produces:
  29 - "application/json;charset=utf-8"
  30 tags:
  31 - name: "ServiceSpecification"
  32   description: ""
  33 paths:
  34   /serviceSpecification:
  35     get:
  36       tags:
  37       - "ServiceSpecification"
  38       produces:
  39       - "application/json;charset=utf-8"
  40       operationId: "serviceSpecificationFind"
  41       summary: "List service specifications"
  42       description: "This operation returns service specifications from a catalog.\n\
  43         Only a predefined set of attribute is proposed : Based on SDC limitations,\
  44         \ only attributes category and distributionStatus are available for serviceSpecification\
  45         \ filtering\nFields attribute could be used to filter attributes retrieved"
  46       deprecated: false
  47       parameters:
  48       - name: "fields"
  49         required: false
  50         in: "query"
  51         description: "Field selection - used to filtering the attributes to be retreived"
  52         type: "string"
  53       - name: "category"
  54         required: false
  55         in: "query"
  56         description: "Service Category (filter)"
  57         type: "string"
  58       - name: "distributionStatus"
  59         required: false
  60         in: "query"
  61         description: "Service distribution status (filter)"
  62         type: "string"
  63       responses:
  64         200:
  65           description: "Ok"
  66           schema:
  67             type: "array"
  68             items:
  69               $ref: "#/definitions/ServiceSpecification"
  70         400:
  71           description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
  72             \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
  73             \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
  74             \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
  75             \ parameter value"
  76           schema:
  77             $ref: "#/definitions/ErrorRepresentation"
  78         401:
  79           description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
  80             \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
  81           schema:
  82             $ref: "#/definitions/ErrorRepresentation"
  83         403:
  84           description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
  85             \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
  86             \ requests"
  87           schema:
  88             $ref: "#/definitions/ErrorRepresentation"
  89         404:
  90           description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
  91             \ not found"
  92           schema:
  93             $ref: "#/definitions/ErrorRepresentation"
  94         422:
  95           description: "Unprocessable entity\n\nFunctional error"
  96           schema:
  97             $ref: "#/definitions/ErrorRepresentation"
  98         500:
  99           description: "Internal Server Error\n\nList of supported error codes:\n\
 100             - 1: Internal error"
 101           schema:
 102             $ref: "#/definitions/ErrorRepresentation"
 103         503:
 104           description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
 105             \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
 106             \ retry later !"
 107           schema:
 108             $ref: "#/definitions/ErrorRepresentation"
 109   /serviceSpecification/{id}:
 110     get:
 111       tags:
 112       - "ServiceSpecification"
 113       produces:
 114       - "application/json;charset=utf-8"
 115       operationId: "serviceSpecificationGet"
 116       summary: "Retrieve a service specification"
 117       description: "This operation returns a service specification by its id from\
 118         \ a catalog. Attribute selection is enabled using the fields attribute."
 119       deprecated: false
 120       parameters:
 121       - name: "id"
 122         required: true
 123         in: "path"
 124         type: "string"
 125       - name: "fields"
 126         required: false
 127         in: "query"
 128         description: "Attribute selection"
 129         type: "string"
 130       responses:
 131         200:
 132           description: "Ok"
 133           schema:
 134             $ref: "#/definitions/ServiceSpecification"
 135         400:
 136           description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
 137             \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
 138             \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
 139             \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
 140             \ parameter value"
 141           schema:
 142             $ref: "#/definitions/ErrorRepresentation"
 143         401:
 144           description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
 145             \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
 146           schema:
 147             $ref: "#/definitions/ErrorRepresentation"
 148         403:
 149           description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
 150             \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
 151             \ requests"
 152           schema:
 153             $ref: "#/definitions/ErrorRepresentation"
 154         404:
 155           description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
 156             \ not found"
 157           schema:
 158             $ref: "#/definitions/ErrorRepresentation"
 159         422:
 160           description: "Unprocessable entity\n\nFunctional error"
 161           schema:
 162             $ref: "#/definitions/ErrorRepresentation"
 163         500:
 164           description: "Internal Server Error\n\nList of supported error codes:\n\
 165             - 1: Internal error"
 166           schema:
 167             $ref: "#/definitions/ErrorRepresentation"
 168         503:
 169           description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
 170             \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
 171             \ retry later !"
 172           schema:
 173             $ref: "#/definitions/ErrorRepresentation"
 174 definitions:
 175   LifecycleStatusValues:
 176     description: "Service lifecycle value from ONAP SDC"
 177     type: "string"
 178     enum:
 179     - "NOT_CERTIFIED_CHECKOUT"
 180     - "NOT_CERTIFIED_CHECKIN"
 181     - "READY_FOR_CERTIFICATION"
 182     - "CERTIFICATION_IN_PROGRESS"
 183     - "CERTIFIED"
 184   DistributionStatus:
 185     description: "Service distribution status from ONAP."
 186     type: "string"
 187     enum:
 188     - "DISTRIBUTION_NOT_APPROVED"
 189     - "DISTRIBUTION_APPROVED"
 190     - "DISTRIBUTED"
 191     - "DISTRIBUTION_REJECTED"
 192   ErrorRepresentation:
 193     description: "This class is used to describe error.\nfor nbi Beijing release we\
 194       \ do not manage additional error for serviceCatalog"
 195     required:
 196     - "code"
 197     - "reason"
 198     type: "object"
 199     properties:
 200       code:
 201         description: "Application related code (as defined in the API or from a common\
 202           \ list)"
 203         type: "integer"
 204         format: "int32"
 205       reason:
 206         description: "Text that explains the reason for error. This can be shown to\
 207           \ a client user."
 208         type: "string"
 209       message:
 210         description: "Text that provide more details and corrective actions related\
 211           \ to the error. This can be shown to a client user"
 212         type: "string"
 213       status:
 214         description: "http error code extension like 400-2"
 215         type: "string"
 216       referenceErrror:
 217         description: "url pointing to documentation describing the error"
 218         type: "string"
 219       '@type':
 220         description: "The class type of a REST resource."
 221         type: "string"
 222       '@schemaLocation':
 223         description: "it provides a link to the schema describing a REST resource."
 224         type: "string"
 225   TimePeriod:
 226     description: "A time period"
 227     type: "object"
 228     properties:
 229       startDateTime:
 230         description: "Start date and time of the period"
 231         type: "string"
 232         format: "date-time"
 233       endDateTime:
 234         description: "End date and time of the period"
 235         type: "string"
 236         format: "date-time"
 237   RelatedPartyRef:
 238     description: "Party linked to the service catalog.\nin nbi we retrieve information\
 239       \ about last updater of the service in SDC"
 240     type: "object"
 241     properties:
 242       id:
 243         description: "Unique identifier of the related party. Filled with lastUpdaterUserId"
 244         type: "string"
 245       role:
 246         description: "Role payed by the related party\nOnly role 'lastUpdater' is\
 247           \ retrieved in Beijing release"
 248         type: "string"
 249       name:
 250         description: "Name of the related party - Filled with lastUpdatedFullName"
 251         type: "string"
 252   ServiceSpecification:
 253     description: "ServiceSpecification is a class that offers characteristics to describe\
 254       \ a type of service. Functionally, it acts as a template by which Services may\
 255       \ be instantiated. By sharing the same specification, these services would therefore\
 256       \ share the same set of characteristics.\nthe service information are retrieved\
 257       \ in SDC"
 258     required:
 259     - "invariantUUID"
 260     type: "object"
 261     properties:
 262       id:
 263         description: "Unique identifier of the service specification. Filled with\
 264           \ SDC Service uuid"
 265         type: "string"
 266       href:
 267         description: "Reference of the service specification- not mapped in Beijing"
 268         type: "string"
 269       name:
 270         description: "Name of the service specification- Filled with SDC Service name"
 271         type: "string"
 272       description:
 273         description: "A narrative that explains in detail what the service specification\
 274           \ is - Filled with SDC Service description"
 275         type: "string"
 276       '@type':
 277         description: "This attribute allows to dynamically extends TMF class. Valued\
 278           \ with 'ONAPservice'. We used this features to add following attributes:\n\
 279           invariantUUID\ntoscaModelURL\ntoscaResourceName\ncategory (1)\nsubcategory\
 280           \ (1)\ndistributionStatus"
 281         type: "string"
 282         default: "ONAPservice"
 283       '@schemaLocation':
 284         description: "Not used for Beijing release"
 285         type: "string"
 286       '@baseType':
 287         description: "Not used for Beijing release"
 288         type: "string"
 289       invariantUUID:
 290         description: "Additional attribute (not in the TMF API) - extended through\
 291           \ @type - invariantUUID"
 292         type: "string"
 293       toscaModelURL:
 294         description: "Additional attribute (not in the TMF API) - extended through\
 295           \ @type - toscaModelURL"
 296         type: "string"
 297       toscaResourceName:
 298         description: "Additional attribute (not in the TMF API) - extended through\
 299           \ @type - toscaResourceName"
 300         type: "string"
 301       category:
 302         description: "Additional attribute - extended through @type - category\nPlease\
 303           \ note that this attribute is managed in TMF - in future release we'll introduce\
 304           \ category resource"
 305         type: "string"
 306       subcategory:
 307         description: "Additional attribute - extended through @type - category\nPlease\
 308           \ note that this attribute is managed in TMF - in future release we'll introduce\
 309           \ category resourc"
 310         type: "string"
 311       distributionStatus:
 312         $ref: "#/definitions/DistributionStatus"
 313       version:
 314         description: "Service specification version - Filled with SDC Service version"
 315         type: "string"
 316       lifecycleStatus:
 317         $ref: "#/definitions/LifecycleStatusValues"
 318       targetServiceSchema:
 319         $ref: "#/definitions/TargetServiceSchemaRef"
 320       attachment:
 321         type: "array"
 322         items:
 323           $ref: "#/definitions/Attachment"
 324       relatedParty:
 325         type: "array"
 326         items:
 327           $ref: "#/definitions/RelatedPartyRef"
 328       resourceSpecification:
 329         type: "array"
 330         items:
 331           $ref: "#/definitions/ResourceSpecificationRef"
 332       serviceSpecCharacteristic:
 333         type: "array"
 334         items:
 335           $ref: "#/definitions/ServiceSpecCharacteristic"
 336   ServiceSpecCharacteristic:
 337     description: "A characteristic quality or distinctive feature of a ServiceSpecification.\
 338       \ \nServiceSpecCharacteristic are retrieved in the serviceTosca file in the\
 339       \ topology_template section in the inputs section."
 340     type: "object"
 341     properties:
 342       name:
 343         description: "Name of the characteristic - Filled with parameter_name"
 344         type: "string"
 345       description:
 346         description: "A narrative that explains in detail what the characteristic\
 347           \ is - Filled with parameter_description"
 348         type: "string"
 349       valueType:
 350         description: "A kind of value that the characteristic can take on, such as\
 351           \ numeric, text and so forth - Filled with parameter_type"
 352         type: "string"
 353       '@type':
 354         description: "This attribute allows to dynamically extends TMF class. Valued\
 355           \ with: 'ONAPserviceCharacteristic'. We do not used this features in nbi\
 356           \ Beijing release."
 357         type: "string"
 358       '@schemaLocation':
 359         description: "An url pointing to type description - we do not use it in nbi\
 360           \ Beijing release"
 361         type: "string"
 362       required:
 363         description: "A parameter to define if the characteristic is mandatory - Filled\
 364           \ from parameter_required – if not fielded by default ‘true’"
 365         type: "boolean"
 366         default: true
 367       status:
 368         description: "Status of the characteristic - filled with status_value"
 369         type: "string"
 370       serviceSpecCharacteristicValue:
 371         type: "array"
 372         items:
 373           $ref: "#/definitions/ServiceSpecCharacteristicValue"
 374   Attachment:
 375     description: "An attachment is a file uses to describe the service.\nIn nbi we\
 376       \ use attachment to retrieve ONAP artifacts."
 377     type: "object"
 378     properties:
 379       id:
 380         description: "Unique identifier of the attachment - filled with artifactUUID."
 381         type: "string"
 382       name:
 383         description: "Name of the attachment - filled with artifactName"
 384         type: "string"
 385       description:
 386         description: "Description of the attachment - filled with artifactDescription"
 387         type: "string"
 388       '@type':
 389         description: "This attribute allows to dynamically extends TMF class. Valued\
 390           \ with 'ONAPartifact'. We used this features to add following attributes:\
 391           \ \nartifactLabel\nartifactGroupType\nartifactTimeout\nartifactChecksum\n\
 392           artifactVersion\ngeneratedFromUUID"
 393         type: "string"
 394         default: "ONAPartifact"
 395       artifactLabel:
 396         description: "Additional attribute (not in the TMF API) - extended through\
 397           \ @type - artifactLabel"
 398         type: "string"
 399       artifactGroupType:
 400         description: "Additional attribute (not in the TMF API) - extended through\
 401           \ @type - artifactGroupType"
 402         type: "string"
 403       artifactTimeout:
 404         description: "Additional attribute (not in the TMF API) - extended through\
 405           \ @type - artifactTimeout"
 406         type: "string"
 407       artifactChecksum:
 408         description: "Additional attribute (not in the TMF API) - extended through\
 409           \ @type - artifactChecksum"
 410         type: "string"
 411       artifactVersion:
 412         description: "Additional attribute (not in the TMF API) - extended through\
 413           \ @type - artifactVersion"
 414         type: "string"
 415       generatedFromUUID:
 416         description: "Additional attribute (not in the TMF API) - extended through\
 417           \ @type - generatedFromUUID"
 418         type: "string"
 419       url:
 420         description: "Uniform Resource Locator, is a web page address - filled with\
 421           \ artifactURL"
 422         type: "string"
 423       mimeType:
 424         description: "Filled with artifactType"
 425         type: "string"
 426   ServiceSpecCharacteristicValue:
 427     description: "A number or text that can be assigned to a service specification\
 428       \ characteristic.\nServiceSpecCharacteristicValue are retrieved in the service\
 429       \ Tosca file"
 430     type: "object"
 431     properties:
 432       valueType:
 433         description: "A kind of value that the characteristic can take on, such as\
 434           \ numeric, text, and so forth\nRetrieved in the Tosca in the topology_template\
 435           \ section in the inputs section - parameter_type. \nWe do not manage parameter_type=\
 436           \ list or map for Beijing release"
 437         type: "string"
 438       isDefault:
 439         description: "Information calculated from parameter default in the Tosca file"
 440         type: "boolean"
 441       value:
 442         description: "A discrete value that the characteristic can take on"
 443         type: "string"
 444   ResourceSpecificationRef:
 445     description: "A list of resourceSpec identified to deliver the service.\nfor nbi\
 446       \ we retrieve resource information available in service description (through\
 447       \ SDC api) bu as well information retrieved in the TOSCA file."
 448     type: "object"
 449     properties:
 450       id:
 451         description: "Unique identifier of the resource specification - filled with\
 452           \ resourceUUID"
 453         type: "string"
 454       version:
 455         description: "Version for this resource specification - filled with resourceVersion"
 456         type: "string"
 457       name:
 458         description: "Name of the resource specification - filled with resourceName"
 459         type: "string"
 460       '@type':
 461         description: "This attribute allows to dynamically extends TMF class. Valued\
 462           \ with: 'ONAPresource'. We used this features to add following attributes:\n\
 463           resourceInstanceName\nresourceInvariantUUID\nresourceType\nmodelCustomizationName\n\
 464           modelCustomizationId"
 465         type: "string"
 466         default: "ONAPresource"
 467       resourceInstanceName:
 468         description: "Additional attribute (not in the TMF API) - extended through\
 469           \ @type - resourceInstanceName"
 470         type: "string"
 471       resourceInvariantUUID:
 472         description: "Additional attribute (not in the TMF API) - extended through\
 473           \ @type - resourceInvariantUUID"
 474         type: "string"
 475       resourceType:
 476         description: "Additional attribute (not in the TMF API) - extended through\
 477           \ @type - resoucreType"
 478         type: "string"
 479       modelCustomizationName:
 480         description: "Additional attribute (not in the TMF API) - extended through\
 481           \ @type - Retrieved in the TOSCA file : attribute name in topology_template/node_template\
 482           \ for the resource"
 483         type: "string"
 484       modelCustomizationId:
 485         description: "Additional attribute (not in the TMF API) - extended through\
 486           \ @type - Retrieved in the TOSCA file : attribute customizationUUID in topology_template/node_template\
 487           \ for the resource"
 488         type: "string"
 489   TargetServiceSchemaRef:
 490     description: ""
 491     required:
 492     - "@type"
 493     - "@schemaLocation"
 494     type: "object"
 495     properties:
 496       '@type':
 497         description: ""
 498         type: "string"
 499       '@schemaLocation':
 500         description: ""
 501         type: "string"