add API documentations

Issue-ID: EXTAPI-40

Change-Id: If700a2e2700f7c19e22c8f5d11ddf425eb0075a5
Signed-off-by: Rene Robert <rene.robert@orange.com>

1 files changed, 487 insertions, 0 deletions

diff --git a/docs/offeredapis/serviceCatalog/asciiDoc.adoc b/docs/offeredapis/serviceCatalog/asciiDoc.adoc
new file mode 100644
index 0000000..327f239
--- /dev/null
+++ b/docs/offeredapis/serviceCatalog/asciiDoc.adoc
@@ -0,0 +1,487 @@
+= API ServiceCatalog
+
+
+[[_overview]]
+== Overview
+
+=== Api URL
+
+https://api-designer.sso.infra.ftgroup/swagger-ui/?url=https://api-designer.sso.infra.ftgroup/api/1.0/apis/N3ma89X1x0/swagger.json[Swagger 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[plant UML UI]
+
+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
+[%hardbreaks]
+__Version__ : 1.0.0_inProgress
+
+
+=== URI scheme
+[%hardbreaks]
+__Host__ : serverRoot
+__BasePath__ : /nbi/api/v1
+__Schemes__ : HTTPS
+
+
+=== Tags
+
+* ServiceSpecification
+
+
+=== Consumes
+
+* `application/json;charset=utf-8`
+
+
+=== Produces
+
+* `application/json;charset=utf-8`
+
+
+[[_paths]]
+== Resources
+
+[[_servicespecification_resource]]
+=== ServiceSpecification
+
+[[_servicespecificationfind]]
+==== 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
+
+[options="header", cols=".^2,.^3,.^9,.^4"]
+|===
+|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
+
+[options="header", cols=".^2,.^14,.^4"]
+|===
+|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>>
+|===
+
+
+[[_servicespecificationget]]
+==== 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
+
+[options="header", cols=".^2,.^3,.^9,.^4"]
+|===
+|Type|Name|Description|Schema
+|**Path**|**id** +
+__required__||string
+|**Query**|**fields** +
+__optional__|Attribute selection|string
+|===
+
+
+===== Responses
+
+[options="header", cols=".^2,.^14,.^4"]
+|===
+|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]]
+== Definitions
+
+[[_attachment]]
+=== Attachment
+An attachment is a file uses to describe the service.
+In nbi we use attachment to retrieve ONAP artifacts.
+
+
+[options="header", cols=".^3,.^11,.^4"]
+|===
+|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]]
+=== DistributionStatus
+Service distribution status from ONAP.
+
+__Type__ : enum (DISTRIBUTION_NOT_APPROVED, DISTRIBUTION_APPROVED, DISTRIBUTED, DISTRIBUTION_REJECTED)
+
+
+[[_errorrepresentation]]
+=== ErrorRepresentation
+This class is used to describe error.
+for nbi Beijing release we do not manage additional error for serviceCatalog
+
+
+[options="header", cols=".^3,.^11,.^4"]
+|===
+|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]]
+=== LifecycleStatusValues
+Service lifecycle value from ONAP SDC
+
+__Type__ : enum (NOT_CERTIFIED_CHECKOUT, NOT_CERTIFIED_CHECKIN, READY_FOR_CERTIFICATION, CERTIFICATION_IN_PROGRESS, CERTIFIED)
+
+
+[[_relatedpartyref]]
+=== RelatedPartyRef
+Party linked to the service catalog.
+in nbi we retrieve information about last updater of the service in SDC
+
+
+[options="header", cols=".^3,.^11,.^4"]
+|===
+|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]]
+=== 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.
+
+
+[options="header", cols=".^3,.^11,.^4"]
+|===
+|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]]
+=== 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.
+
+
+[options="header", cols=".^3,.^11,.^4"]
+|===
+|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]]
+=== ServiceSpecCharacteristicValue
+A number or text that can be assigned to a service specification characteristic.
+ServiceSpecCharacteristicValue are retrieved in the service Tosca file
+
+
+[options="header", cols=".^3,.^11,.^4"]
+|===
+|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
+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
+
+
+[options="header", cols=".^3,.^11,.^4"]
+|===
+|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]]
+=== TargetServiceSchemaRef
+
+[options="header", cols=".^3,.^4"]
+|===
+|Name|Schema
+|**@schemaLocation** +
+__required__|string
+|**@type** +
+__required__|string
+|===
+
+
+[[_timeperiod]]
+=== TimePeriod
+A time period
+
+
+[options="header", cols=".^3,.^11,.^4"]
+|===
+|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)
+|===
+