docs/offeredapis/serviceInventory/asciiDoc.adoc

   1 ////
   2 This work is licensed under a Creative Commons Attribution 4.0 International License.
   3 http://creativecommons.org/licenses/by/4.0
   4 Copyright 2018 Orange
   5 ////
   6
   7 = API ServiceInventory
   8
   9
  10 [[_overview]]
  11 == Overview
  12
  13 === Api URL
  14
  15 https://api-designer.sso.infra.ftgroup/swagger-ui/?url=https://api-designer.sso.infra.ftgroup/api/1.0/apis/5an735gnX0/swagger.json[Swagger UI]
  16
  17
  18 https://plantuml.rd.francetelecom.fr/proxy?fmt=svg&src=https://api-designer.sso.infra.ftgroup/api/1.0/apis/5an735gnX0/plantuml&noCache=304710.0[plant UML UI]
  19
  20 serviceInventory API designed for ONAP Beijing Release.
  21 This API is build from TMF open API18.0 (applying TMF Guideline 3.0)
  22 only operation GET (by id &amp; byList) for resource serviceSpecification is available
  23
  24
  25 === Version information
  26 [%hardbreaks]
  27 __Version__ : 1.0.0_inProgress
  28
  29
  30 === URI scheme
  31 [%hardbreaks]
  32 __Host__ : serverRoot
  33 __BasePath__ : /nbi/api/v1
  34 __Schemes__ : HTTPS
  35
  36
  37 === Tags
  38
  39 * Service
  40
  41
  42 === Consumes
  43
  44 * `application/json;charset=utf-8`
  45
  46
  47 === Produces
  48
  49 * `application/json;charset=utf-8`
  50
  51
  52 [[_paths]]
  53 == Resources
  54
  55 [[_service_resource]]
  56 === Service
  57
  58 [[_servicefind]]
  59 ==== List services
  60 ....
  61 GET /service
  62 ....
  63
  64
  65 ===== Description
  66 This operation list service entities.
  67 Attribute selection is restricted.
  68 fields attribute may be used to filter retrieved attribute(s) for each service
  69
  70 Specific business errors for current operation will be encapsulated in
  71
  72 HTTP Response 422 Unprocessable entity
  73
  74
  75 ===== Parameters
  76
  77 [options="header", cols=".^2,.^3,.^4"]
  78 |===
  79 |Type|Name|Schema
  80 |**Query**|**fields** +
  81 __optional__|string
  82 |**Query**|**id** +
  83 __optional__|string
  84 |**Query**|**relatedParty.id** +
  85 __optional__|string
  86 |**Query**|**serviceSpecification.id** +
  87 __optional__|string
  88 |**Query**|**serviceSpecification.name** +
  89 __optional__|string
  90 |===
  91
  92
  93 ===== Responses
  94
  95 [options="header", cols=".^2,.^14,.^4"]
  96 |===
  97 |HTTP Code|Description|Schema
  98 |**200**|Success|< <<_listservice,ListService>> > array
  99 |**400**|Bad Request
 100
 101 List of supported error codes:
 102 - 20: Invalid URL parameter value
 103 - 21: Missing body
 104 - 22: Invalid body
 105 - 23: Missing body field
 106 - 24: Invalid body field
 107 - 25: Missing header
 108 - 26: Invalid header value
 109 - 27: Missing query-string parameter
 110 - 28: Invalid query-string parameter value|<<_errorrepresentation,ErrorRepresentation>>
 111 |**401**|Unauthorized
 112
 113 List of supported error codes:
 114 - 40: Missing credentials
 115 - 41: Invalid credentials
 116 - 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>>
 117 |**403**|Forbidden
 118
 119 List of supported error codes:
 120 - 50: Access denied
 121 - 51: Forbidden requester
 122 - 52: Forbidden user
 123 - 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>>
 124 |**404**|Not Found
 125
 126 List of supported error codes:
 127 - 60: Resource not found|<<_errorrepresentation,ErrorRepresentation>>
 128 |**422**|Unprocessable entity
 129
 130 Functional error|<<_errorrepresentation,ErrorRepresentation>>
 131 |**500**|Internal Server Error
 132
 133 List of supported error codes:
 134 - 1: Internal error|<<_errorrepresentation,ErrorRepresentation>>
 135 |**503**|Service Unavailable
 136
 137 List of supported error codes:
 138 - 5: The service is temporarily unavailable
 139 - 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>>
 140 |===
 141
 142
 143 [[_serviceget]]
 144 ==== Retrieve a service
 145 ....
 146 GET /service/{id}
 147 ....
 148
 149
 150 ===== Description
 151 This operation retrieves a service entity.
 152 Attribute selection is enabled for all first level attributes.
 153
 154 Specific business errors for current operation will be encapsulated in
 155
 156 HTTP Response 422 Unprocessable entity
 157
 158
 159 ===== Parameters
 160
 161 [options="header", cols=".^2,.^3,.^4"]
 162 |===
 163 |Type|Name|Schema
 164 |**Path**|**id** +
 165 __required__|string
 166 |**Query**|**relatedParty.id** +
 167 __optional__|string
 168 |**Query**|**serviceSpecification.id** +
 169 __optional__|string
 170 |**Query**|**serviceSpecification.name** +
 171 __optional__|string
 172 |===
 173
 174
 175 ===== Responses
 176
 177 [options="header", cols=".^2,.^14,.^4"]
 178 |===
 179 |HTTP Code|Description|Schema
 180 |**200**|Success|<<_service,Service>>
 181 |**400**|Bad Request
 182
 183 List of supported error codes:
 184 - 20: Invalid URL parameter value
 185 - 21: Missing body
 186 - 22: Invalid body
 187 - 23: Missing body field
 188 - 24: Invalid body field
 189 - 25: Missing header
 190 - 26: Invalid header value
 191 - 27: Missing query-string parameter
 192 - 28: Invalid query-string parameter value|<<_errorrepresentation,ErrorRepresentation>>
 193 |**401**|Unauthorized
 194
 195 List of supported error codes:
 196 - 40: Missing credentials
 197 - 41: Invalid credentials
 198 - 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>>
 199 |**403**|Forbidden
 200
 201 List of supported error codes:
 202 - 50: Access denied
 203 - 51: Forbidden requester
 204 - 52: Forbidden user
 205 - 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>>
 206 |**404**|Not Found
 207
 208 List of supported error codes:
 209 - 60: Resource not found|<<_errorrepresentation,ErrorRepresentation>>
 210 |**422**|Unprocessable entity
 211
 212 Functional error|<<_errorrepresentation,ErrorRepresentation>>
 213 |**500**|Internal Server Error
 214
 215 List of supported error codes:
 216 - 1: Internal error|<<_errorrepresentation,ErrorRepresentation>>
 217 |**503**|Service Unavailable
 218
 219 List of supported error codes:
 220 - 5: The service is temporarily unavailable
 221 - 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>>
 222 |===
 223
 224
 225 [[_definitions]]
 226 == Definitions
 227
 228 [[_errorrepresentation]]
 229 === ErrorRepresentation
 230 This class is used to describe error.
 231 for nbi Beijing release we do not manage additional error for serviceCatalog
 232
 233
 234 [options="header", cols=".^3,.^11,.^4"]
 235 |===
 236 |Name|Description|Schema
 237 |**@schemaLocation** +
 238 __optional__|it provides a link to the schema describing a REST resource.|string
 239 |**@type** +
 240 __optional__|The class type of a REST resource.|string
 241 |**code** +
 242 __required__|Application related code (as defined in the API or from a common list)|integer (int32)
 243 |**message** +
 244 __optional__|Text that provide more details and corrective actions related to the error. This can be shown to a client user.|string
 245 |**reason** +
 246 __required__|Text that explains the reason for error. This can be shown to a client user.|string
 247 |**referenceError** +
 248 __optional__|url pointing to documentation describing the error|string
 249 |**status** +
 250 __optional__|http error code extension like 400-2|string
 251 |===
 252
 253
 254 [[_listrelatedpartyref]]
 255 === ListRelatedPartyRef
 256 This class is used to structure list of service(s) retrieved
 257
 258
 259 [options="header", cols=".^3,.^11,.^4"]
 260 |===
 261 |Name|Description|Schema
 262 |**id** +
 263 __optional__|Unique identifier of a related party|string
 264 |**role** +
 265 __optional__|Role played by the related party - only role “ONAPcustomer” is managed in Beijing release.|string
 266 |===
 267
 268
 269 [[_listservice]]
 270 === ListService
 271 This class is used to structure list of service(s) retrieved
 272
 273
 274 [options="header", cols=".^3,.^11,.^4"]
 275 |===
 276 |Name|Description|Schema
 277 |**id** +
 278 __optional__|Unique identifier of the service|string
 279 |**name** +
 280 __optional__|Name of the service|string
 281 |**relatedParty** +
 282 __optional__||<<_listrelatedpartyref,ListRelatedPartyRef>>
 283 |**serviceSpecification** +
 284 __optional__||<<_listservicespecificationref,ListServiceSpecificationRef>>
 285 |===
 286
 287
 288 [[_listservicespecificationref]]
 289 === ListServiceSpecificationRef
 290 This class is used to structure list of service(s) retrieved
 291
 292
 293 [options="header", cols=".^3,.^11,.^4"]
 294 |===
 295 |Name|Description|Schema
 296 |**id** +
 297 __optional__|Unique identifier of the service specification|string
 298 |**name** +
 299 __optional__|Name of the required service specification|string
 300 |===
 301
 302
 303 [[_relatedpartyref]]
 304 === RelatedPartyRef
 305 RelatedParty reference. A related party defines party or party role linked to a specific entity.
 306 Only ONAP Customer is managed in Beijing release.
 307
 308
 309 [options="header", cols=".^3,.^11,.^4"]
 310 |===
 311 |Name|Description|Schema
 312 |**@referredType** +
 313 __optional__|Not managed in the Beijing release.|string
 314 |**href** +
 315 __optional__|Reference of a related party.
 316 Not filled in Beijing release.|string
 317 |**id** +
 318 __optional__|Unique identifier of a related party|string
 319 |**role** +
 320 __optional__|Role played by the related party.
 321 Filled with 'ONAPcustomer'|string
 322 |===
 323
 324
 325 [[_service]]
 326 === Service
 327 Instantiated service (service_instance) in AAI
 328
 329
 330 [options="header", cols=".^3,.^11,.^4"]
 331 |===
 332 |Name|Description|Schema
 333 |**@baseType** +
 334 __optional__|Not managed in Beijing release|string
 335 |**@schemaLocation** +
 336 __optional__|Not managed in Beijing release|string
 337 |**@type** +
 338 __optional__|This attribute allows to dynamically extends TMF class. Not used in Beijing release.|string
 339 |**characteristic** +
 340 __optional__||< <<_servicecharacteristic,ServiceCharacteristic>> > array
 341 |**hasStarted** +
 342 __optional__|This is a Boolean attribute that, if TRUE, signifies that this Service has already been started. If the value of this attribute is FALSE, then this signifies that this Service has NOT been Started
 343 Not managed in Beijing release|boolean
 344 |**href** +
 345 __optional__|Reference of the service
 346 Not managed in Beijing release|string
 347 |**id** +
 348 __optional__|Unique identifier of the service - Valued with service-instance-id|string
 349 |**name** +
 350 __optional__|Name of the service - Valued with service-instance-name|string
 351 |**relatedParty** +
 352 __optional__||< <<_relatedpartyref,RelatedPartyRef>> > array
 353 |**serviceSpecification** +
 354 __optional__||<<_servicespecificationref,ServiceSpecificationRef>>
 355 |**state** +
 356 __optional__||<<_statevalues,stateValues>>
 357 |**supportingResource** +
 358 __optional__||< <<_supportingresource,SupportingResource>> > array
 359 |**type** +
 360 __optional__|Service type - valued with 'service-instance'|string
 361 |===
 362
 363
 364 [[_servicecharacteristic]]
 365 === ServiceCharacteristic
 366 A list of name value pairs that define the service characteristics
 367 Not managed in Beijing release.
 368
 369
 370 [options="header", cols=".^3,.^11,.^4"]
 371 |===
 372 |Name|Description|Schema
 373 |**name** +
 374 __required__|Name of the characteristic
 375 Not managed in Beijing release.|string
 376 |**value** +
 377 __optional__||<<_value,Value>>
 378 |**valueType** +
 379 __optional__|Type of value for this characteristic.
 380 Not managed in Beijing release.|string
 381 |===
 382
 383
 384 [[_servicespecificationref]]
 385 === ServiceSpecificationRef
 386 Service specification reference: ServiceSpecification of this service (catalog information)
 387
 388
 389 [options="header", cols=".^3,.^11,.^4"]
 390 |===
 391 |Name|Description|Schema
 392 |**@referredType** +
 393 __optional__|This attribute allows to dynamically extends TMF class. Valued with 'ONAPservice'. We used this features to add following attribute: invariantUUID|string
 394 |**@schemaLocation** +
 395 __optional__|Not managed in Beijing release|string
 396 |**href** +
 397 __optional__|Reference of the service specification.
 398 not managed in Beijing release.|string
 399 |**id** +
 400 __optional__|Unique identifier of the service specification. valued to model-version-id|string
 401 |**invariantUUID** +
 402 __optional__|Additional attribute (not in the TMF API) - extended through @referredType - model-invariant-id|string
 403 |**name** +
 404 __optional__|Name of the required service specification|string
 405 |**version** +
 406 __optional__|Service specification version.
 407 Not managed in Beijing release|string
 408 |===
 409
 410
 411 [[_supportingresource]]
 412 === SupportingResource
 413 Supporting resource - A supportingResource will be retrieved for each relationship of the relationship-list where related-link describe a vnf
 414
 415
 416 [options="header", cols=".^3,.^11,.^4"]
 417 |===
 418 |Name|Description|Schema
 419 |**@referredType** +
 420 __optional__|This attribute allows to dynamically extends TMF class. Valued with 'ONAP resource'. We used this features to add following attributes:
 421  status
 422  modelInvariantId
 423  modelVersionId
 424  modelCustomisationId|string
 425 |**@schemaLocation** +
 426 __optional__|Not managed in Beijing release.|string
 427 |**href** +
 428 __optional__|Reference of the supporting resource|string
 429 |**id** +
 430 __optional__|Unique identifier of the supporting resource - Valued to vnf-id|string
 431 |**modelCustomisationId** +
 432 __optional__|Additional attribute (not in the TMF API) - extended through @referredType - valued with model-customisation-id|string
 433 |**modelInvariantId** +
 434 __optional__|Additional attribute (not in the TMF API) - extended through @referredType - valued with model-invariant-id|string
 435 |**modelVersionId** +
 436 __optional__|Additional attribute (not in the TMF API) - extended through @referredType - valued with model-verson-id|string
 437 |**name** +
 438 __optional__|Name of the supporting resource - Valued with vnf_-name|string
 439 |**role** +
 440 __optional__|Not managed in Beijing release.|string
 441 |**status** +
 442 __optional__|Additional attribute (not in the TMF API) - extended through @referredType - valued with prov-status|string
 443 |===
 444
 445
 446 [[_value]]
 447 === Value
 448 Structure used to describe characteristic value.
 449 Not managed in Beijing release.
 450
 451
 452 [options="header", cols=".^3,.^11,.^4"]
 453 |===
 454 |Name|Description|Schema
 455 |**@schemaLocation** +
 456 __optional__|Not managed in Beijing release.|string
 457 |**@type** +
 458 __optional__|Not managed in Beijing release.|string
 459 |**serviceCharacteristicValue** +
 460 __optional__|Not managed in Beijing release.|string
 461 |===
 462
 463
 464 [[_statevalues]]
 465 === stateValues
 466 __Type__ : enum (feasibilityChecked, designed, reserved, inactive, active, terminated)
 467