International License.
.. http://creativecommons.org/licenses/by/4.0
.. Copyright 2018 ORANGE
+.. _offeredapis:
============
be used by external systems as BSS for example. These API are based on
**TMF API**.
-**********************************************
-Global NBI architecture for Casablanca release
-**********************************************
+*******************************************
+Global NBI architecture for El Alto 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_Casablanca.jpg
+.. image:: ../images/onap_nbi_dublin.jpg
:width: 800px
***********
API Version
***********
-APIs are described with a state version with “v” following the API Name,
-e.g.: ``nbi/api/v3/productOrder``.
+APIs are described with a state version with "v" following the API Name,
+e.g.: ``nbi/api/v4/productOrder``.
The schema associated with a REST API must have its version number aligned
with that of the REST API.
- Changes in the cardinality of an attribute in a data type must be from
mandatory to optional or from lower to greater
- New attributes defined in an element must be optional (absence of
- ``use=”required”``).
+ ``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
.. |postman-icon| image:: images/postman.png
:width: 40px
+.. |xml-icon| image:: images/text_xml.png
+ :width: 40px
+
.. csv-table::
- :header: "API", "|swagger-icon|", "|html-icon|", "|plantuml-icon|", "|swagger-icon|", "|postman-icon|", "|pdf-icon|"
- :widths: 10,5,5,5,5,5,5
+ :header: "API", "|swagger-icon|", "|swagger-icon|", "|plantuml-icon|", "|xml-icon|"
+ :widths: 10,5,5,5,5
+
+ " ", "json file", "yaml file", "plant UML file", "xml schemas"
+ "hub", ":download:`link <api_hub/swagger.json>`", ":download:`link <api_hub/swagger.yaml>`", ":download:`link <api_hub/api.plantuml>`", ":download:`link <api_hub/model.xsd>`"
+ "serviceCatalog", ":download:`link <api_serviceCatalog/swagger.json>`", ":download:`link <api_serviceCatalog/swagger.yaml>`", ":download:`link <api_serviceCatalog/api.plantuml>`", ":download:`link <api_serviceCatalog/model.xsd>`"
+ "serviceInventory", ":download:`link <api_serviceInventory/swagger.json>`", ":download:`link <api_serviceInventory/swagger.yaml>`", ":download:`link <api_serviceInventory/api.plantuml>`", ":download:`link <api_serviceInventory/model.xsd>`"
+ "serviceOrder", ":download:`link <api_serviceOrder/swagger.json>`", ":download:`link <api_serviceOrder/swagger.yaml>`", ":download:`link <api_serviceOrder/api.plantuml>`", ":download:`link <api_serviceOrder/model.xsd>`"
+ "status", ":download:`link <api_status/swagger.json>`", ":download:`link <api_status/swagger.yaml>`", ":download:`link <api_status/api.plantuml>`", ":download:`link <api_status/model.xsd>`"
+
+***********************
+API ReDoc Documentation
+***********************
+
+* :doc:`API hub <redoc/api_hub>`
+* :doc:`Service Catalog <redoc/api_serviceCatalog>`
+* :doc:`Service Inventory <redoc/api_serviceInventory>`
+* :doc:`Service Order <redoc/api_serviceOrder>`
+* :doc:`Status <redoc/api_status>`
- " ", "json file", "html doc", "plantUML doc", "Swagger Editor", "Postman Collection", "pdf doc"
- "serviceCatalog", ":download:`link <swaggers/serviceCatalog_3_0_0.json>`", ":download:`link <serviceCatalog/documentation.html>`", ":download:`link <serviceCatalog/apiServiceCatalog.plantuml>`", "coming", "coming", "coming"
- "serviceInventory", ":download:`link <swaggers/serviceInventory_3_0_0.json>`", ":download:`link <serviceInventory/documentation.html>`", ":download:`link <serviceInventory/apiServiceInventory.plantuml>`", "coming", "coming", "coming"
- "serviceOrder", ":download:`link <swaggers/serviceOrder_3_0_0.json>`", ":download:`link <serviceOrder/documentation.html>`", ":download:`link <serviceOrder/apiServiceOrder.plantuml>`", "coming", ":download:`link <postman/ONAPBeijingServiceOrderDoc.postman_collection.json>`", "coming"
- "listener", ":download:`link <swaggers/listener-1_0_0.json>`", ":download:`link <listener/documentation.html>`", ":download:`link <listener/apiListener.plantuml>`", "coming", "coming", "coming"
- "healthCheck", ":download:`link <swaggers/healthCheck_3_0_0.json>`", "coming", "coming", "coming", "coming", "coming"
***************
API Description
**GET serviceSpecification(list)**
-Example: ``GET /nbi/api/v3/serviceSpecification/
+Example: ``GET /nbi/api/v4/serviceSpecification/
?category=NetworkService&distributionStatus=DISTRIBUTED``
It is possible to retrieve a list of ``serviceSpecification`` (get by list).
**GET service Specification (id)**
-Example: ``GET /nbi/api/v3/serviceSpecification/{uuid}``
+Example: ``GET /nbi/api/v4/serviceSpecification/{uuid}``
It is use to retrieve one ``serviceSpecification`` - all available information
are retieved (see Swagger for description)
+**GET service Specification Schema (id)**
+
+Example:
+``GET /nbi/api/v4/serviceSpecification/{uuid}/specificationInputSchema``
+
+It is use to retrieve one input schema from the tosca file stored in **NBI**
+- all available information are retieved (see Swagger for description)
+
----------------
serviceInventory
----------------
**GET Service Inventory (list)**
-Example: ``GET /nbi/api/v3/service/?relatedParty.id=Pontus``
+Example: ``GET /nbi/api/v4/service/?relatedParty.id=Pontus``
GET (by list) allows to request with following criteria (all optional) :
if no service matches, an empty list is send back.
-1. If a request is send without any parameter, we’ll retrieve the list of
+1. If a request is send without any parameter, we'll retrieve the list of
service-instance for the *generic* customer
2. If only customer parameter is filled (``relatedParty.id`` +
- role= relatedParty’ONAPcustomer’) we’ll retrieve the list of
+ role= relatedParty'ONAPcustomer') we'll retrieve the list of
service-instance for this customer
-3. If serviceSpecification.id or name is filled we’ll retrieve the list of
- Service instance (from this service specification) – We’ll use the customer
- id if provided (with Role=’ONAPcustomer) or generic if no customer id
+3. If serviceSpecification.id or name is filled we'll retrieve the list of
+ Service instance (from this service specification) - We'll use the customer
+ id if provided (with Role='ONAPcustomer) or generic if no customer id
provided
**GET Service Inventory (id)**
-Example: ``GET /nbi/api/v3/service/{id}`` When querying for a specific service
+Example: ``GET /nbi/api/v4/service/{id}`` When querying for a specific service
instance id, no additional filters are required.
-The Service Inventory API will retrieve the service instance data from A&AI using
-the nodes query with the service instance id as the key. ``relatedParty.id`` +
-``serviceSpecification.name`` are added to the response based on the A&AI service
-instance url.
+The Service Inventory API will retrieve the service instance data from A&AI
+using the nodes query with the service instance id as the key.
+``relatedParty.id`` + ``serviceSpecification.name`` are added to the response
+based on the A&AI service instance url.
------------
serviceOrder
one service order by providing id or a list of service order. For this release,
only a subset of criteria is available:
-• ``externalId``
-• ``state``
-• ``description``
-• ``orderDate.gt`` (orderDate must be greater – after -than)
-• ``orderDate.lt`` (orderDate must be lower-before - than)
-• ``fields`` – attribute used to filter retrieved attributes (if needed) and
+* ``externalId``
+* ``state``
+* ``description``
+* ``orderDate.gt`` (orderDate must be greater - after -than)
+* ``orderDate.lt`` (orderDate must be lower-before - than)
+* ``fields`` - attribute used to filter retrieved attributes (if needed) and
also for sorted SO
-• ``offset`` and ``limit`` are used for pagination purpose
+* ``offset`` and ``limit`` are used for pagination purpose
ServiceOrder will manage following ``actionItem`` action:
-• ``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
+* ``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
+* Cloud & tenant information MUST BE defined in the external API property file
+* Management of ONAP customer for add service action
With the current version of APIs used from **SO** and **A&AI** 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
+* 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 **A&AI** if not.
-• If no ``relatedParty`` is provided, the service will be affected to
- ``generic customer`` (dummy customer) – we assume this ``generic customer``
+* If no ``relatedParty`` is provided, the service will be affected to
+ ``generic customer`` (dummy customer) - we assume this ``generic customer``
always exists.
-• Additionally **NBI** will create in **A&AI** the service-type if it did not
+* Additionally **NBI** will create in **A&AI** the service-type if it did not
exists for the customer
**ServiceOrder management in NBI will support 2 modes:**
-• E2E integration - **NBI** calls **SO** API to perform an End-To-end
+* E2E integration - **NBI** calls **SO** API to perform an End-To-end
integration
-• Service-level only integration - **NBI** will trigger only **SO** request at
+* Service-level only integration - **NBI** will trigger only **SO** request at
serviceInstance level. **SO** 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” ,
+**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.
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
+* A new service order is created in **NBI**
+* A service order state changes
+* A service order item state changes
+
+It is also possible to subscribe to **AAI** and **SDC** notifications via
+**NBI**.
+4 events are managed:
-These 3 events have distinct notification allowing any system to subscribe to
+* A new service is created in **AAI***
+* A service attribute value is changed in **AAI**
+* A service is removed in **AAI**
+* A service specification is distributed in **SDC**
+
+These 7 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
+* 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
+* 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/``
+ API as client - **NBI** will shoot ``POST listener/``
The following diagram illustrates such notification flow:
.. image:: images/notification.jpg
:width: 800px
+**East-west interaction of ONAP instances through External API**
+
+Operator's SO component will talk to service provider's external API component
+through its own external API component.
+
+External API support two methods of posting a Service Order or registering for
+Hub.
+
+1. If the incoming request is per current implementation (no additional headers
+) then no changes will be made. The request will be serviced per BAU flow.
+2. If the incoming request has additional *Target* header parameters, External
+API will identify that the request has to be relayed to another ONAP instance
+and route the request accordingly.
+
+Target parameter: The public endpoint url for target ONAP instance's External
+API, for instance
+http://externalDomain/nbi/api/vX
+
+* For posting service order and getting service order status, the request will
+ be relayed to target (service provider's External API) as-is. These are
+ synchronous requests and operator's External API will wait for response from
+ the target and relay it back to original calling system (operator's SO).
+* For Hub API, there is an additional step required. The listener from calling
+ system (operator's SO) will be replaced with External APIs own listener.
+ A mapping of registered subscriber and its original listener will be
+ maintained in External API's DB. Operator's External API will relay the Hub
+ API call to service provider's External API. The service provider's External
+ API will register operator's External API as a listener.
+* After SO processing in service provider's ONAP is completed (irrespective of
+ status - reject, success, fail etc), service provider's External API will
+ notify the operator's External API about request completion. Operator's
+ External API will look-up for registered subscriber and its original listener
+ (operator's SO) and relay the message.
+
+Operator's Service Orchestrator will invoke its own External API component and
+add SP Partner URL in the header. After receiving an acknowledgement for
+Service Order request, the SO component will register with External API's hub
+and provide its listener for processing callback events.
+
+Technical information about **East-west interaction exercise** design
+specification and API Flow illustration (with example messages) could be found
+here:
+
+https://wiki.onap.org/download/attachments/8227019/CCVPN%20Phase%202%20HLD.docx?api=v2
+
***************
Developer Guide
Code Review / externalapi / nbi.git / blobdiff