docs/offeredapis/serviceCatalog/asciiDoc.adoc

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