X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fofferedapis%2Fofferedapis.rst;h=66f657efdcada8a6783b8fa7788a5afd6606df61;hb=7471bd7e10998bc5cdfe591ed42b0f4c9eb41205;hp=f575b0151683f0db3b1f316ba86f18ed47a4906d;hpb=5973e241424950c8f6fcf1b9d5a107b19b5a9816;p=externalapi%2Fnbi.git diff --git a/docs/offeredapis/offeredapis.rst b/docs/offeredapis/offeredapis.rst index f575b01..66f657e 100644 --- a/docs/offeredapis/offeredapis.rst +++ b/docs/offeredapis/offeredapis.rst @@ -2,6 +2,7 @@ International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2018 ORANGE +.. _offeredapis: ============ @@ -15,9 +16,9 @@ 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 Dublin release -********************************************** +******************************************** +Global NBI architecture for Honolulu release +******************************************** Following illustration provides a global view about **NBI** architecture, integration with other ONAP components and API resource/operation provided. @@ -25,12 +26,24 @@ integration with other ONAP components and API resource/operation provided. .. image:: ../images/onap_nbi_dublin.jpg :width: 800px +************ +API Endpoint +************ + +Since Frankfurt, in an OOM ONAP deployment context: + +https://nbi.api.simpledemo.onap.org:30274/nbi/api/v4 + +Locally, for dev and testing purpose: + +http://localhost:8080/nbi/api/v4 + *********** 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. @@ -46,7 +59,7 @@ provided the following backward compatibility rules are respected: - 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 @@ -93,6 +106,17 @@ API Table "serviceOrder", ":download:`link `", ":download:`link `", ":download:`link `", ":download:`link `" "status", ":download:`link `", ":download:`link `", ":download:`link `", ":download:`link `" +*********************** +API ReDoc Documentation +*********************** + +- `hub <./hub.html>`_ +- `serviceCatalog <./service_catalog.html>`_ +- `serviceInventory <./service_inventory.html>`_ +- `serviceOrder <./service_order.html>`_ +- `status <./status.html>`_ + + *************** API Description *************** @@ -106,7 +130,6 @@ is 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 does 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 @@ -121,7 +144,7 @@ Only *basic* service characteristics will be managed in this release. By **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). @@ -134,17 +157,30 @@ If no ``serviceSpecification`` matches, an empty list is send back. **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) +are retrieved (see Swagger for description) **GET service Specification Schema (id)** -Example: ``GET /nbi/api/v3/serviceSpecification/{uuid}/specificationInputSchema`` +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 retrieved (see Swagger for description) + +**POST service Specification** -It is use to retrieve one input schema from the tosca file stored in **NBI** - all available -information are retieved (see Swagger for description) +Example: + +``POST /nbi/api/v4/serviceSpecification`` + +This operation creates a ``serviceSpecification`` in catalog (see Swagger for description) +It is used to provide a consistent way of on-boarding third party services to SDC via External API + +Only *primitive type* service characteristics are supported as part of this release. Further enhancements +need to be made on other modules of ONAP for ensuring e2e automation of third party services. ---------------- serviceInventory @@ -159,7 +195,7 @@ and ``type`` **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) : @@ -172,25 +208,25 @@ 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 @@ -204,53 +240,53 @@ 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`` -• ``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. @@ -273,34 +309,80 @@ addtionnal information about ``serviceOrder`` management. 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**. +It is also possible to subscribe to **AAI** and **SDC** notifications via +**NBI**. 4 events are managed: -• 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** +* 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