From 7afe844fb9f4171697ff5b82b86b2161ffbf2a78 Mon Sep 17 00:00:00 2001 From: Rene Robert Date: Wed, 28 Mar 2018 09:55:53 +0000 Subject: add API documentations Issue-ID: EXTAPI-40 Change-Id: If700a2e2700f7c19e22c8f5d11ddf425eb0075a5 Signed-off-by: Rene Robert --- docs/offeredapis/serviceCatalog/markDown.md | 294 ++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 docs/offeredapis/serviceCatalog/markDown.md (limited to 'docs/offeredapis/serviceCatalog/markDown.md') diff --git a/docs/offeredapis/serviceCatalog/markDown.md b/docs/offeredapis/serviceCatalog/markDown.md new file mode 100644 index 0000000..4d066c3 --- /dev/null +++ b/docs/offeredapis/serviceCatalog/markDown.md @@ -0,0 +1,294 @@ +# API ServiceCatalog + + + +## Overview + +### Api URL + +[Swagger UI](https://api-designer.sso.infra.ftgroup/swagger-ui/?url=https://api-designer.sso.infra.ftgroup/api/1.0/apis/N3ma89X1x0/swagger.json) + + +[plant UML UI](https://plantuml.rd.francetelecom.fr/proxy?fmt=svg&src=https://api-designer.sso.infra.ftgroup/api/1.0/apis/N3ma89X1x0/plantuml&noCache=797767.0) + +serviceCatalog API designed for ONAP Beijing Release. +This API is build from TMF open API17.5. +Only operation GET (by id & byList) for resource serviceSpecification is available + + +### Version information +*Version* : 1.0.0_inProgress + + +### URI scheme +*Host* : serverRoot +*BasePath* : /nbi/api/v1 +*Schemes* : HTTPS + + +### Tags + +* ServiceSpecification + + +### Consumes + +* `application/json;charset=utf-8` + + +### Produces + +* `application/json;charset=utf-8` + + + +## Resources + + +### ServiceSpecification + + +#### List service specifications +``` +GET /serviceSpecification +``` + + +##### Description +This operation returns service specifications from a catalog. +Only a predefined set of attribute is proposed : Based on SDC limitations, only attributes category and distributionStatus are available for serviceSpecification filtering +Fields attribute could be used to filter attributes retrieved + +Specific business errors for current operation will be encapsulated in + +HTTP Response 422 Unprocessable entity + + +##### Parameters + +|Type|Name|Description|Schema| +|---|---|---|---| +|**Query**|**category**
*optional*|Service Category (filter)|string| +|**Query**|**distributionStatus**
*optional*|Service distribution status (filter)|string| +|**Query**|**fields**
*optional*|Field selection - used to filtering the attributes to be retreived|string| + + +##### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|Success|< [ServiceSpecification](#servicespecification) > array| +|**400**|Bad Request

List of supported error codes:
- 20: Invalid URL parameter value
- 21: Missing body
- 22: Invalid body
- 23: Missing body field
- 24: Invalid body field
- 25: Missing header
- 26: Invalid header value
- 27: Missing query-string parameter
- 28: Invalid query-string parameter value|[ErrorRepresentation](#errorrepresentation)| +|**401**|Unauthorized

List of supported error codes:
- 40: Missing credentials
- 41: Invalid credentials
- 42: Expired credentials|[ErrorRepresentation](#errorrepresentation)| +|**403**|Forbidden

List of supported error codes:
- 50: Access denied
- 51: Forbidden requester
- 52: Forbidden user
- 53: Too many requests|[ErrorRepresentation](#errorrepresentation)| +|**404**|Not Found

List of supported error codes:
- 60: Resource not found|[ErrorRepresentation](#errorrepresentation)| +|**422**|Unprocessable entity

Functional error|[ErrorRepresentation](#errorrepresentation)| +|**500**|Internal Server Error

List of supported error codes:
- 1: Internal error|[ErrorRepresentation](#errorrepresentation)| +|**503**|Service Unavailable

List of supported error codes:
- 5: The service is temporarily unavailable
- 6: Orange API is over capacity, retry later !|[ErrorRepresentation](#errorrepresentation)| + + + +#### Retrieve a service specification +``` +GET /serviceSpecification/{id} +``` + + +##### Description +This operation returns a service specification by its id from a catalog. Attribute selection is enabled using the fields attribute. + +Specific business errors for current operation will be encapsulated in + +HTTP Response 422 Unprocessable entity + + +##### Parameters + +|Type|Name|Description|Schema| +|---|---|---|---| +|**Path**|**id**
*required*||string| +|**Query**|**fields**
*optional*|Attribute selection|string| + + +##### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|Success|[ServiceSpecification](#servicespecification)| +|**400**|Bad Request

List of supported error codes:
- 20: Invalid URL parameter value
- 21: Missing body
- 22: Invalid body
- 23: Missing body field
- 24: Invalid body field
- 25: Missing header
- 26: Invalid header value
- 27: Missing query-string parameter
- 28: Invalid query-string parameter value|[ErrorRepresentation](#errorrepresentation)| +|**401**|Unauthorized

List of supported error codes:
- 40: Missing credentials
- 41: Invalid credentials
- 42: Expired credentials|[ErrorRepresentation](#errorrepresentation)| +|**403**|Forbidden

List of supported error codes:
- 50: Access denied
- 51: Forbidden requester
- 52: Forbidden user
- 53: Too many requests|[ErrorRepresentation](#errorrepresentation)| +|**404**|Not Found

List of supported error codes:
- 60: Resource not found|[ErrorRepresentation](#errorrepresentation)| +|**422**|Unprocessable entity

Functional error|[ErrorRepresentation](#errorrepresentation)| +|**500**|Internal Server Error

List of supported error codes:
- 1: Internal error|[ErrorRepresentation](#errorrepresentation)| +|**503**|Service Unavailable

List of supported error codes:
- 5: The service is temporarily unavailable
- 6: Orange API is over capacity, retry later !|[ErrorRepresentation](#errorrepresentation)| + + + +## Definitions + + +### Attachment +An attachment is a file uses to describe the service. +In nbi we use attachment to retrieve ONAP artifacts. + + +|Name|Description|Schema| +|---|---|---| +|**@type**
*optional*|This attribute allows to dynamically extends TMF class. Valued with 'ONAPartifact'. We used this features to add following attributes:
artifactLabel
artifactGroupType
artifactTimeout
artifactChecksum
artifactVersion
generatedFromUUID
**Default** : `"ONAPartifact"`|string| +|**artifactChecksum**
*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactChecksum|string| +|**artifactGroupType**
*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactGroupType|string| +|**artifactLabel**
*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactLabel|string| +|**artifactTimeout**
*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactTimeout|string| +|**artifactVersion**
*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactVersion|string| +|**description**
*optional*|Description of the attachment - filled with artifactDescription|string| +|**generatedFromUUID**
*optional*|Additional attribute (not in the TMF API) - extended through @type - generatedFromUUID|string| +|**id**
*optional*|Unique identifier of the attachment - filled with artifactUUID.|string| +|**mimeType**
*optional*|Filled with artifactType|string| +|**name**
*optional*|Name of the attachment - filled with artifactName|string| +|**url**
*optional*|Uniform Resource Locator, is a web page address - filled with artifactURL|string| + + + +### DistributionStatus +Service distribution status from ONAP. + +*Type* : enum (DISTRIBUTION_NOT_APPROVED, DISTRIBUTION_APPROVED, DISTRIBUTED, DISTRIBUTION_REJECTED) + + + +### ErrorRepresentation +This class is used to describe error. +for nbi Beijing release we do not manage additional error for serviceCatalog + + +|Name|Description|Schema| +|---|---|---| +|**@schemaLocation**
*optional*|it provides a link to the schema describing a REST resource.|string| +|**@type**
*optional*|The class type of a REST resource.|string| +|**code**
*required*|Application related code (as defined in the API or from a common list)|integer (int32)| +|**message**
*optional*|Text that provide more details and corrective actions related to the error. This can be shown to a client user|string| +|**reason**
*required*|Text that explains the reason for error. This can be shown to a client user.|string| +|**referenceErrror**
*optional*|url pointing to documentation describing the error|string| +|**status**
*optional*|http error code extension like 400-2|string| + + + +### LifecycleStatusValues +Service lifecycle value from ONAP SDC + +*Type* : enum (NOT_CERTIFIED_CHECKOUT, NOT_CERTIFIED_CHECKIN, READY_FOR_CERTIFICATION, CERTIFICATION_IN_PROGRESS, CERTIFIED) + + + +### RelatedPartyRef +Party linked to the service catalog. +in nbi we retrieve information about last updater of the service in SDC + + +|Name|Description|Schema| +|---|---|---| +|**id**
*optional*|Unique identifier of the related party. Filled with lastUpdaterUserId|string| +|**name**
*optional*|Name of the related party - Filled with lastUpdatedFullName|string| +|**role**
*optional*|Role payed by the related party
Only role 'lastUpdater' is retrieved in Beijing release|string| + + + +### ResourceSpecificationRef +A list of resourceSpec identified to deliver the service. +for nbi we retrieve resource information available in service description (through SDC api) bu as well information retrieved in the TOSCA file. + + +|Name|Description|Schema| +|---|---|---| +|**@type**
*optional*|This attribute allows to dynamically extends TMF class. Valued with: 'ONAPresource'. We used this features to add following attributes:
resourceInstanceName
resourceInvariantUUID
resourceType
modelCustomizationName
modelCustomizationId
**Default** : `"ONAPresource"`|string| +|**id**
*optional*|Unique identifier of the resource specification - filled with resourceUUID|string| +|**modelCustomizationId**
*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| +|**modelCustomizationName**
*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| +|**name**
*optional*|Name of the resource specification - filled with resourceName|string| +|**resourceInstanceName**
*optional*|Additional attribute (not in the TMF API) - extended through @type - resourceInstanceName|string| +|**resourceInvariantUUID**
*optional*|Additional attribute (not in the TMF API) - extended through @type - resourceInvariantUUID|string| +|**resourceType**
*optional*|Additional attribute (not in the TMF API) - extended through @type - resoucreType|string| +|**version**
*optional*|Version for this resource specification - filled with resourceVersion|string| + + + +### ServiceSpecCharacteristic +A characteristic quality or distinctive feature of a ServiceSpecification. +ServiceSpecCharacteristic are retrieved in the serviceTosca file in the topology_template section in the inputs section. + + +|Name|Description|Schema| +|---|---|---| +|**@schemaLocation**
*optional*|An url pointing to type description - we do not use it in nbi Beijing release|string| +|**@type**
*optional*|This attribute allows to dynamically extends TMF class. Valued with: 'ONAPserviceCharacteristic'. We do not used this features in nbi Beijing release.|string| +|**description**
*optional*|A narrative that explains in detail what the characteristic is - Filled with parameter_description|string| +|**name**
*optional*|Name of the characteristic - Filled with parameter_name|string| +|**required**
*optional*|A parameter to define if the characteristic is mandatory - Filled from parameter_required – if not fielded by default ‘true’
**Default** : `true`|boolean| +|**serviceSpecCharacteristicValue**
*optional*||< [ServiceSpecCharacteristicValue](#servicespeccharacteristicvalue) > array| +|**status**
*optional*|Status of the characteristic - filled with status_value|string| +|**valueType**
*optional*|A kind of value that the characteristic can take on, such as numeric, text and so forth - Filled with parameter_type|string| + + + +### ServiceSpecCharacteristicValue +A number or text that can be assigned to a service specification characteristic. +ServiceSpecCharacteristicValue are retrieved in the service Tosca file + + +|Name|Description|Schema| +|---|---|---| +|**isDefault**
*optional*|Information calculated from parameter default in the Tosca file|boolean| +|**value**
*optional*|A discrete value that the characteristic can take on|string| +|**valueType**
*optional*|A kind of value that the characteristic can take on, such as numeric, text, and so forth
Retrieved in the Tosca in the topology_template section in the inputs section - parameter_type.
We do not manage parameter_type= list or map for Beijing release|string| + + + +### ServiceSpecification +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. +the service information are retrieved in SDC + + +|Name|Description|Schema| +|---|---|---| +|**@baseType**
*optional*|Not used for Beijing release|string| +|**@schemaLocation**
*optional*|Not used for Beijing release|string| +|**@type**
*optional*|This attribute allows to dynamically extends TMF class. Valued with 'ONAPservice'. We used this features to add following attributes:
invariantUUID
toscaModelURL
toscaResourceName
category (1)
subcategory (1)
distributionStatus
**Default** : `"ONAPservice"`|string| +|**attachment**
*optional*||< [Attachment](#attachment) > array| +|**category**
*optional*|Additional attribute - extended through @type - category
Please note that this attribute is managed in TMF - in future release we'll introduce category resource|string| +|**description**
*optional*|A narrative that explains in detail what the service specification is - Filled with SDC Service description|string| +|**distributionStatus**
*optional*||[DistributionStatus](#distributionstatus)| +|**href**
*optional*|Reference of the service specification- not mapped in Beijing|string| +|**id**
*optional*|Unique identifier of the service specification. Filled with SDC Service uuid|string| +|**invariantUUID**
*required*|Additional attribute (not in the TMF API) - extended through @type - invariantUUID|string| +|**lifecycleStatus**
*optional*||[LifecycleStatusValues](#lifecyclestatusvalues)| +|**name**
*optional*|Name of the service specification- Filled with SDC Service name|string| +|**relatedParty**
*optional*||< [RelatedPartyRef](#relatedpartyref) > array| +|**resourceSpecification**
*optional*||< [ResourceSpecificationRef](#resourcespecificationref) > array| +|**serviceSpecCharacteristic**
*optional*||< [ServiceSpecCharacteristic](#servicespeccharacteristic) > array| +|**subcategory**
*optional*|Additional attribute - extended through @type - category
Please note that this attribute is managed in TMF - in future release we'll introduce category resourc|string| +|**targetServiceSchema**
*optional*||[TargetServiceSchemaRef](#targetserviceschemaref)| +|**toscaModelURL**
*optional*|Additional attribute (not in the TMF API) - extended through @type - toscaModelURL|string| +|**toscaResourceName**
*optional*|Additional attribute (not in the TMF API) - extended through @type - toscaResourceName|string| +|**version**
*optional*|Service specification version - Filled with SDC Service version|string| + + + +### TargetServiceSchemaRef + +|Name|Schema| +|---|---| +|**@schemaLocation**
*required*|string| +|**@type**
*required*|string| + + + +### TimePeriod +A time period + + +|Name|Description|Schema| +|---|---|---| +|**endDateTime**
*optional*|End date and time of the period|string (date-time)| +|**startDateTime**
*optional*|Start date and time of the period|string (date-time)| + -- cgit 1.2.3-korg