Add API Documentation for Casablanca

-change docs

Change-Id: I1ed30a0c329951aa7c20b752ccbcbf07ad640afd
Issue-ID: EXTAPI-141
Signed-off-by: romaingimbert <romain.gimbert@orange.com>

17 files changed, 120 insertions, 108 deletions

diff --git a/docs/architecture/architecture.rst b/docs/architecture/architecture.rst
index 6b58dcd..31f0235 100644..100755
--- a/docs/architecture/architecture.rst
+++ b/docs/architecture/architecture.rst
@@ -18,13 +18,13 @@ These API are based on **TMF API**.
 
 
 *******************************************
-Global NBI architecture for Beijing release
+Global NBI architecture for Casablanca release
 *******************************************
 
 Following illustration provides a global view about NBI architecture,
 integration with other ONAP components and API resource/operation provided.
 
-.. image:: images/ONAP_External_ID_Beijing.jpg
+.. image:: images/ONAP_External_ID_Casablanca.jpg
    :width: 800px
 
 
diff --git a/docs/architecture/images/ONAP_External_ID_Beijing.jpg b/docs/architecture/images/ONAP_External_ID_Beijing.jpg
index 8fbd4ab..8fbd4ab 100644..100755
--- a/docs/architecture/images/ONAP_External_ID_Beijing.jpg
+++ b/docs/architecture/images/ONAP_External_ID_Beijing.jpg
diff --git a/docs/architecture/images/ONAP_External_ID_Casablanca.jpg b/docs/architecture/images/ONAP_External_ID_Casablanca.jpg
new file mode 100755
index 0000000..a566e42
--- /dev/null
+++ b/docs/architecture/images/ONAP_External_ID_Casablanca.jpg
diff --git a/docs/consumedapis/consumedapis.rst b/docs/consumedapis/consumedapis.rst
index 6ca0932..38418b3 100644..100755
--- a/docs/consumedapis/consumedapis.rst
+++ b/docs/consumedapis/consumedapis.rst
@@ -56,14 +56,26 @@ will be retrieve in service inventory: id, name and type
 SO API
 ******
 
-This API is used to perform Service Order and thus instantiate a service
-
+This API is used to perform Service Order and thus instantiate a service.
+Distinct SO APIs are used for serviceInstance creation request depending on the serviceSpecification category (set in SDC).
+If service could be delivered end-to-end from one request category is set to 'E2E Service'. 
+In this case NBI uses 
 
 ::
 
-    MSO_CREATE_SERVICE_INSTANCE_PATH = "/ecomp/mso/infra/serviceInstance/v6"
+    MSO_CREATE_E2ESERVICE_INSTANCE_PATH = "/ecomp/mso/infra/e2eServiceInstances/v3"
 
     MSO_GET_REQUEST_STATUS_PATH = "/ecomp/mso/infra/orchestrationRequests/v6/"
 
     MSO_DELETE_REQUEST_STATUS_PATH = "/ecomp/mso/infra/serviceInstances/v6/"
 
+	
+else following API are used:
+
+::
+
+    MSO_CREATE_SERVICE_INSTANCE_PATH = "/ecomp/mso/infra/serviceInstance/v6"
+
+    MSO_GET_REQUEST_STATUS_PATH = "/ecomp/mso/infra/orchestrationRequests/v6/"
+
+    MSO_DELETE_REQUEST_STATUS_PATH = "/ecomp/mso/infra/serviceInstances/v6/"
\ No newline at end of file
diff --git a/docs/offeredapis/images/ONAP_External_ID_Beijing.jpg b/docs/offeredapis/images/ONAP_External_ID_Beijing.jpg
index 8fbd4ab..8fbd4ab 100644..100755
--- a/docs/offeredapis/images/ONAP_External_ID_Beijing.jpg
+++ b/docs/offeredapis/images/ONAP_External_ID_Beijing.jpg
diff --git a/docs/offeredapis/images/ONAP_External_ID_Casablanca.jpg b/docs/offeredapis/images/ONAP_External_ID_Casablanca.jpg
new file mode 100755
index 0000000..a566e42
--- /dev/null
+++ b/docs/offeredapis/images/ONAP_External_ID_Casablanca.jpg
diff --git a/docs/offeredapis/images/html.png b/docs/offeredapis/images/html.png
index f1bda88..f1bda88 100644..100755
--- a/docs/offeredapis/images/html.png
+++ b/docs/offeredapis/images/html.png
diff --git a/docs/offeredapis/images/notification.jpg b/docs/offeredapis/images/notification.jpg
new file mode 100755
index 0000000..672a885
--- /dev/null
+++ b/docs/offeredapis/images/notification.jpg
diff --git a/docs/offeredapis/images/pdf.png b/docs/offeredapis/images/pdf.png
index fed52f9..fed52f9 100644..100755
--- a/docs/offeredapis/images/pdf.png
+++ b/docs/offeredapis/images/pdf.png
diff --git a/docs/offeredapis/images/postman.png b/docs/offeredapis/images/postman.png
index cab386c..cab386c 100644..100755
--- a/docs/offeredapis/images/postman.png
+++ b/docs/offeredapis/images/postman.png
diff --git a/docs/offeredapis/images/swagger.png b/docs/offeredapis/images/swagger.png
index f5a9e0c..f5a9e0c 100644..100755
--- a/docs/offeredapis/images/swagger.png
+++ b/docs/offeredapis/images/swagger.png
diff --git a/docs/offeredapis/images/swaggerUI.png b/docs/offeredapis/images/swaggerUI.png
index f5a9e0c..f5a9e0c 100644..100755
--- a/docs/offeredapis/images/swaggerUI.png
+++ b/docs/offeredapis/images/swaggerUI.png
diff --git a/docs/offeredapis/images/uml.jpg b/docs/offeredapis/images/uml.jpg
index d288c6c..d288c6c 100644..100755
--- a/docs/offeredapis/images/uml.jpg
+++ b/docs/offeredapis/images/uml.jpg
diff --git a/docs/offeredapis/index.rst b/docs/offeredapis/index.rst
index 248029e..0146813 100644..100755
--- a/docs/offeredapis/index.rst
+++ b/docs/offeredapis/index.rst
@@ -13,12 +13,12 @@ Introduction
 NBI stands for NorthBound Interface. It brings to ONAP a set of API that can be used by external systems as BSS for example. These API are based on **TMF API**.
 
 *******************************************
-Global NBI architecture for Beijing release
+Global NBI architecture for Casablanca release
 *******************************************
 
 Following illustration provides a global view about nbi architecture,integration with other ONAP components and API resource/operation provided.
 
-.. image:: images/ONAP_External_ID_Beijing.jpg
+.. image:: images/ONAP_External_ID_Casablanca.jpg
    :width: 800px
 
 ***********
@@ -40,9 +40,7 @@ For minor modifications of the API, version numbering must not be updated, provi
 - New attributes defined in an element must be optional (absence of use=”required”).
 - If new enumerated values are included, the former ones and its meaning must be kept.
 - If new operations are added, the existing operations must be kept
-- New parameters added to existing operations must be optional and existing parameters
-
-must be kept
+- New parameters added to existing operations must be optional and existing parameters must be kept
 
 For major modifications of the API, not backward compatible and forcing client implementations to be changed, the version number must be updated.
 
@@ -122,7 +120,7 @@ From TMF638 serviceInventory
 API at a glance:
 Only high level information are provided - swagger is documented.
 
-This API retrieves service(s) in the AAI inventory. Only following attributes will be retrieve in service inventory: id, name and type (no state or startDate available )
+This API retrieves service(s) in the AAI inventory. Only following attributes will be retrieve in service inventory: id, name, state and type.
 
 GET Service Inventory (list):
 
@@ -168,9 +166,11 @@ It is possible to use POST operation to create new serviceOrder in NBI and trigg
 •	fields – attribute used to filter retrieved attributes (if needed) and also for sorted SO
 •	offset and limit are used for pagination purpose
 
+ServiceOrder will manage following actioItem action:
 
-
-ServiceOrder will manage only ‘add’ and ‘delete’ operation (no change).
+•	add - a new service will be created
+•	delete - an existing service will be deleted
+•	change - an existing service will be deleted and then created with new attribute value
 
 prerequisites & assumptions :
 
@@ -182,15 +182,49 @@ With the current version of APIs used from SO and AAI we need to manage a ‘cus
 •	It could be provided through a serviceOrder in the service Order a relatedParty with role ‘ONAPcustomer’ should be provided in the serviceOrder header (we will not consider in this release the party at item level); External API component will check if this customer exists and create it in AAI if not.
 •	If no relatedParty are provided the service will be affected to ‘generic’ customer (dummy customer) – we assume this ‘generic’ customer always exists.
 •	Additionally nbi will create in AAI the service-type if it did not exists for the customer
-•	Integration is done at service-level: nbi will trigger only SO request at serviceInstance level -->  ONAP prerequisite: SO must be able to find a BPMN to process service fulfillment (integrate vnf, vnf activation in SDNC, VF module
-•	State management: States are only managed by ServiceOrder component and could not be updated from north side via API. Accordingly to service order item fulfillment progress, order item state are updated. Order state is automatically updated based on item state.
+
+ServiceOrder management in NBI will support 2 modes:
+
+•	E2E integration - NBI call SO API to perform an End-To-end integration 
+•	Service-level only integration - nbi will trigger only SO request at serviceInstance level -->  ONAPSO prerequisite: SO must be able to find a BPMN to process service fulfillment (integrate vnf, vnf activation in SDNC, VF module
+
+The choice of the mode is done in NBI depending on information retrieved in SDC. If the serviceSpecification is within a Category “E2E Service” , NBI will use E2E SO API, if not only API at service instance level will be used.
+
+There is no difference or specific expectation in the service order API used by NBI user. 
+
+ServiceOrder tracking
+
+State management: States are only managed by ServiceOrder component and could not be updated from north side via API. 
+Accordingly to service order item fulfillment progress, order item state are updated. Order state is automatically updated based on item state.
+Additionnally to this state, NBI provided a completion percent progress to have detailled information about order progress. 
+Order Message are retrieved in the GET serviceOrder to provide NBI used addtionnal information about serviceOrder management. 
+
+**Notification:**
+
+It is possible for an external system to subscribe to service order notifications. 3 events are managed:
+
+•	A new service order is created in NBI
+•	A service order state changes.
+•	A service order item state changes
+
+These 3 events have distinct notification allowing any system to subscribe to one, two or all notification types.
+
+The implementation will be split in 2 components:
+
+•	A HUB resource must be managed within the NBI/serviceOrder API. This HUB resource allows system to subscribe to NBI notification
+•	An Event API must be available at listener side in order to be able to receive Listener (when event occurs). NBI will be upgraded to use this API as client – NBI will shoot POST listener/
+
+Following diagram illustrate an illustrative notification flow:
+
+.. image:: images/notification.jpg
+   :width: 800px
 
 
 ***************
 Developer Guide
 ***************
 
-Technical information about NBI (dependancies, configuration, running & testing) could be found here: :doc:`NBI_R1_Developer_Guide <../architecture/NBI_R1_Developer_Guide>`
+Technical information about NBI (dependancies, configuration, running & testing) could be found here: :doc:`NBI_Developer_Guide <../architecture/NBI_Developer_Guide>`
 
 API Flow illustration (with example messages) is described in this document: :download:`nbicallflow.pdf <pdf/nbicallflow.pdf>`
 
diff --git a/docs/offeredapis/offeredapis.rst b/docs/offeredapis/offeredapis.rst
index 3c52aa7..c2d1cdd 100644..100755
--- a/docs/offeredapis/offeredapis.rst
+++ b/docs/offeredapis/offeredapis.rst
@@ -3,8 +3,9 @@
 .. Copyright 2018 ORANGE
 
 
-Offered APIs
-============
+==================================================
+nbi - northbound interface - External API for ONAP
+==================================================
 ************
 Introduction
 ************
@@ -12,19 +13,19 @@ Introduction
 NBI stands for NorthBound Interface. It brings to ONAP a set of API that can be used by external systems as BSS for example. These API are based on **TMF API**.
 
 *******************************************
-Global NBI architecture for Beijing release
+Global NBI architecture for Casablanca release
 *******************************************
 
 Following illustration provides a global view about nbi architecture,integration with other ONAP components and API resource/operation provided.
 
-.. image:: images/ONAP_External_ID_Beijing.jpg
+.. image:: images/ONAP_External_ID_Casablanca.jpg
    :width: 800px
 
 ***********
 API Version
 ***********
 
-APIs are described with a  state version with “v” following the API Name, e.g.:  nbi/api/v1/productOrder.
+APIs are described with a  state version with “v” following the API Name, e.g.:  'nbi/api/v1/productOrder'.
 The schema associated with a REST API must have its version number aligned with that of the REST API.
 
 The version number has major, minor and revision numbers. E.g. v1.0.0
@@ -40,6 +41,7 @@ For minor modifications of the API, version numbering must not be updated, provi
 - If new enumerated values are included, the former ones and its meaning must be kept.
 - If new operations are added, the existing operations must be kept
 - New parameters added to existing operations must be optional and existing parameters
+
 must be kept
 
 For major modifications of the API, not backward compatible and forcing client implementations to be changed, the version number must be updated.
@@ -89,16 +91,16 @@ API at a glance:
 Only high level information are provided - swagger is documented.
 
 Only serviceSpecification resource is provided.
-Information are retrieved in SDC (and in Tosca file) - Only GET operation is provided - this API DID NOT UPDATE SDC
+Information are retrieved in SDC (and in TOSCA file) - Only GET operation is provided - this API DID NOT UPDATE SDC
 
-Only characteristics at service level will be retrieved in ONAP Tosca file. For example if an ONAP service is composed of VNF and the VF module, the serviceSpecification resource will only feature characteristic describe in the ONAP service tosca model and not attributes in the tosca files for VNF or VF module.
+Only characteristics at service level will be retrieved in ONAP TOSCA file. For example if an ONAP service is composed of VNF and the VF module, the serviceSpecification resource will only feature characteristic describe in the ONAP service tosca model and not attributes in the tosca files for VNF or VF module.
 
 Only ‘basic’ service characteristics will be managed in this release. By ‘basic’ we mean string, boolean, integer parameter type and we do not manage ‘map’ or ‘list parameter type
 
 
 GET serviceSpecification(list)
 
-(example: GET /nbi/api/v1/serviceSpecification/?category=NetworkService&distributionStatus =DISTRIBUTED)
+(example: GET /nbi/api/v1/serviceSpecification/?category=NetworkService&distributionStatus=DISTRIBUTED)
 
 It is possible to retrieve a list of serviceSpecification (get by list).
 
@@ -106,7 +108,7 @@ Only attributes category and distributionStatus are available for serviceSpecifi
 
 if no serviceSpecification matches, an empty list is send back.
 
-GET service Specification (id)
+GET tservice Specification (id)
 
 (example: GET /nbi/api/v1/serviceSpecification/{uuid})
 
@@ -120,7 +122,7 @@ From TMF638 serviceInventory
 API at a glance:
 Only high level information are provided - swagger is documented.
 
-This API retrieves service(s) in the AAI inventory. Only following attributes will be retrieve in service inventory: id, name and type (no state or startDate available )
+This API retrieves service(s) in the AAI inventory. Only following attributes will be retrieve in service inventory: id, name, state and type.
 
 GET Service Inventory (list):
 
@@ -156,7 +158,7 @@ From TMF641 serviceOrder
 API at a glance:
 Only high level information are provided - swagger is documented.
 
-It is possible to use POST operation to create new serviceOrder in nbi and triggers service provisioning. GET operation is also available to retrieve one service order by providing id or a list of service order. For this release, only a subset of criteria is available:
+It is possible to use POST operation to create new serviceOrder in NBI and triggers service provisioning. GET operation is also available to retrieve one service order by providing id or a list of service order. For this release, only a subset of criteria is available:
 
 •	externalId
 •	state
@@ -166,29 +168,65 @@ It is possible to use POST operation to create new serviceOrder in nbi and trigg
 •	fields – attribute used to filter retrieved attributes (if needed) and also for sorted SO
 •	offset and limit are used for pagination purpose
 
+ServiceOrder will manage following actioItem action:
 
-
-ServiceOrder will manage only ‘add’ and ‘delete’ operation (no change).
+•	add - a new service will be created
+•	delete - an existing service will be deleted
+•	change - an existing service will be deleted and then created with new attribute value
 
 prerequisites & assumptions :
 
 •	Cloud & tenant information MUST BE defined in the external API property file
-•	Management of ONAP customer for add service action:
+•	Management of ONAP customer for add service action
+
 With the current version of APIs used from SO and AAI we need to manage a ‘customer’. This customer concept is confusing with Customer BSS concept. We took the following rules to manage the ‘customer’ information:
 
 •	It could be provided through a serviceOrder in the service Order a relatedParty with role ‘ONAPcustomer’ should be provided in the serviceOrder header (we will not consider in this release the party at item level); External API component will check if this customer exists and create it in AAI if not.
 •	If no relatedParty are provided the service will be affected to ‘generic’ customer (dummy customer) – we assume this ‘generic’ customer always exists.
-
 •	Additionally nbi will create in AAI the service-type if it did not exists for the customer
 
-•	Integration is done at service-level: nbi will trigger only SO request at serviceInstance level -->  ONAP prerequisite: SO must be able to find a BPMN to process service fulfillment (integrate vnf, vnf activation in SDNC, VF module
+ServiceOrder management in NBI will support 2 modes:
+
+•	E2E integration - NBI call SO API to perform an End-To-end integration 
+•	Service-level only integration - nbi will trigger only SO request at serviceInstance level -->  ONAPSO prerequisite: SO must be able to find a BPMN to process service fulfillment (integrate vnf, vnf activation in SDNC, VF module
+
+The choice of the mode is done in NBI depending on information retrieved in SDC. If the serviceSpecification is within a Category “E2E Service” , NBI will use E2E SO API, if not only API at service instance level will be used.
+
+There is no difference or specific expectation in the service order API used by NBI user. 
+
+ServiceOrder tracking
+
+State management: States are only managed by ServiceOrder component and could not be updated from north side via API. 
+Accordingly to service order item fulfillment progress, order item state are updated. Order state is automatically updated based on item state.
+Additionnally to this state, NBI provided a completion percent progress to have detailled information about order progress. 
+Order Message are retrieved in the GET serviceOrder to provide NBI used addtionnal information about serviceOrder management. 
+
+**Notification:**
 
-•	State management: States are only managed by ServiceOrder component and could not be updated from north side via API. Accordingly to service order item fulfillment progress, order item state are updated. Order state is automatically updated based on item state.
+It is possible for an external system to subscribe to service order notifications. 3 events are managed:
 
+•	A new service order is created in NBI
+•	A service order state changes.
+•	A service order item state changes
+
+These 3 events have distinct notification allowing any system to subscribe to one, two or all notification types.
+
+The implementation will be split in 2 components:
+
+•	A HUB resource must be managed within the NBI/serviceOrder API. This HUB resource allows system to subscribe to NBI notification
+•	An Event API must be available at listener side in order to be able to receive Listener (when event occurs). NBI will be upgraded to use this API as client – NBI will shoot POST listener/
+
+Following diagram illustrate an illustrative notification flow:
+
+.. image:: images/notification.jpg
+   :width: 800px
+
+
+***************
+Developer Guide
+***************
 
-********
-API flow
-********
+Technical information about NBI (dependancies, configuration, running & testing) could be found here: :doc:`NBI_Developer_Guide <../architecture/NBI_Developer_Guide>`
 
 API Flow illustration (with example messages) is described in this document: :download:`nbicallflow.pdf <pdf/nbicallflow.pdf>`
 
diff --git a/docs/offeredapis/pdf/nbicallflow.pdf b/docs/offeredapis/pdf/nbicallflow.pdf
index 0763c55..c84f0dc 100644..100755
--- a/docs/offeredapis/pdf/nbicallflow.pdf
+++ b/docs/offeredapis/pdf/nbicallflow.pdf
diff --git a/docs/releasenotes/releasenotes.rst b/docs/releasenotes/releasenotes.rst
deleted file mode 100644
index bf74d88..0000000
--- a/docs/releasenotes/releasenotes.rst
+++ /dev/null
@@ -1,72 +0,0 @@
-.. This work is licensed under a
-.. Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. Copyright 2018 ORANGE
-
-Release Notes
-=============
-
-Version: 1.0.0
---------------
-
-:Release Date: 2018-06-07
-
-**New Features**
-
-Main features are:
-
-- `EXTAPI-39 <https://jira.onap.org/browse/EXTAPI-39>`_ - Retrieve SDC information (catalog information) for service level artifacts based on TMF633 open APIs - operation GET
-- `EXTAPI-41 <https://jira.onap.org/browse/EXTAPI-41>`_ - Retrieve AAI information (inventory information) for service instance level artifacts based on TMF638 open APIs - operation GET
-- `EXTAPI-42 <https://jira.onap.org/browse/EXTAPI-42>`_ - Create and retrieve SO service request for service level based on TMF641 open APIS - Operations POST & GET
-
-Detail of features described in the readTheDoc documentation.
-
-**Bug Fixes**
-
-Not applicable - This is an initial release
-
-**Known Issues**
-
-For service catalog:
-
-- Find criteria are limited
-
-For service inventory:
-
-- Customer information must be passed to get complete service representation.
-- Find criteria are limited.
-
-For service order:
-
-- ServiceOrder will manage only ‘add’ and ‘delete’ operation (no change).
-- Only service level request is performed.
-- No request for VNF/VF and no call to SDNC.
-- `EXTAPI-70 <https://jira.onap.org/browse/EXTAPI-70>`_ : links between customer/service instance and cloud/tenant not done (trigger VID issue).
-- Only active service state is considered to add a service.
-
-Detail of limitations described in the readTheDoc documentation.
-
-**Security Notes**
-
-External API code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, items that remain open have been assessed for risk and determined to be false positive. The External API open Critical security vulnerabilities and their risk assessment have been documented as part of the `project <https://wiki.onap.org/pages/viewpage.action?pageId=28382906>`_.
-Authentication management and Data Access rights have not been implemented.
-
-Quick Links:
-
-- `External API project page <https://wiki.onap.org/display/DW/External+API+Framework+Project>`_
-- `Passing Badge information for External API <https://bestpractices.coreinfrastructure.org/en/projects/1771>`_
-- `Project Vulnerability Review Table for External API <https://wiki.onap.org/pages/viewpage.action?pageId=28382906>`_
-
-**Upgrade Notes**
-
-Not applicable - This is an initial release
-
-**Deprecation Notes**
-
-Not applicable - This is an initial release
-
-**Other**
-
-===========
-
-End of Release Notes