1 .. This work is licensed under a Creative Commons Attribution 4.0
3 .. http://creativecommons.org/licenses/by/4.0
4 .. Copyright 2018 ORANGE
15 NBI stands for NorthBound Interface. It brings to ONAP a set of API that can
16 be used by external systems as BSS for example. These API are based on
19 *******************************************
20 Global NBI architecture for Guilin release
21 *******************************************
23 Following illustration provides a global view about **NBI** architecture,
24 integration with other ONAP components and API resource/operation provided.
26 .. image:: ../images/onap_nbi_dublin.jpg
33 Since Frankfurt, in an OOM ONAP deployment context:
35 https://nbi.api.simpledemo.onap.org:30274/nbi/api/v4
37 Locally, for dev and testing purpose:
39 http://localhost:8080/nbi/api/v4
45 APIs are described with a state version with "v" following the API Name,
46 e.g.: ``nbi/api/v4/productOrder``.
47 The schema associated with a REST API must have its version number aligned
48 with that of the REST API.
50 The version number has major, minor and revision numbers. E.g. v1.0.0
51 The version number (without the revision number) is held in the URI.
53 The major version number is incremented for an incompatible change.
54 The minor version number is incremented for a compatible change.
55 For minor modifications of the API, version numbering must not be updated,
56 provided the following backward compatibility rules are respected:
58 - New elements in a data type must be optional (``minOccurs=0``)
59 - Changes in the cardinality of an attribute in a data type must be from
60 mandatory to optional or from lower to greater
61 - New attributes defined in an element must be optional (absence of
63 - If new enumerated values are included, the former ones and its meaning must
65 - If new operations are added, the existing operations must be kept
66 - New parameters added to existing operations must be optional and existing
67 parameters must be kept
69 For major modifications of the API, not backward compatible and forcing client
70 implementations to be changed, the version number must be updated.
76 .. |pdf-icon| image:: images/pdf.png
79 .. |swagger-icon| image:: images/swagger.png
83 .. |swaggerUI-icon| image:: images/swaggerUI.png
86 .. |html-icon| image:: images/html.png
89 .. |plantuml-icon| image:: images/uml.jpg
92 .. |postman-icon| image:: images/postman.png
95 .. |xml-icon| image:: images/text_xml.png
99 :header: "API", "|swagger-icon|", "|swagger-icon|", "|plantuml-icon|", "|xml-icon|"
102 " ", "json file", "yaml file", "plant UML file", "xml schemas"
103 "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>`"
104 "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>`"
105 "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>`"
106 "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>`"
107 "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>`"
109 ***********************
110 API ReDoc Documentation
111 ***********************
113 * :doc:`API hub <redoc/api_hub>`
114 * :doc:`Service Catalog <redoc/api_serviceCatalog>`
115 * :doc:`Service Inventory <redoc/api_serviceInventory>`
116 * :doc:`Service Order <redoc/api_serviceOrder>`
117 * :doc:`Status <redoc/api_status>`
128 This API is based from TMF633 serviceCatalog. Only high level information
129 is provided - Swagger is documented.
131 Only ``serviceSpecification`` resource is provided.
132 Information are retrieved in **SDC** (and in TOSCA file)
134 Only characteristics at service level will be retrieved in ONAP TOSCA file.
135 For example if an ONAP service is composed of VNF and the VF module, the
136 ``serviceSpecification`` resource will only feature characteristic described in
137 the ONAP service TOSCA model and not attributes in the TOSCA files for VNF
140 Only *basic* service characteristics will be managed in this release. By
141 *basic* we mean string, boolean, integer parameter type and we do not manage
142 *map* or *list* parameter type.
145 **GET serviceSpecification(list)**
147 Example: ``GET /nbi/api/v4/serviceSpecification/
148 ?category=NetworkService&distributionStatus=DISTRIBUTED``
150 It is possible to retrieve a list of ``serviceSpecification`` (get by list).
152 Only attributes ``category`` and ``distributionStatus`` are available for
153 ``serviceSpecification`` filtering. It is possible to select retrieved
154 attributes using fields attribute.
156 If no ``serviceSpecification`` matches, an empty list is send back.
158 **GET service Specification (id)**
160 Example: ``GET /nbi/api/v4/serviceSpecification/{uuid}``
162 It is use to retrieve one ``serviceSpecification`` - all available information
163 are retrieved (see Swagger for description)
165 **GET service Specification Schema (id)**
168 ``GET /nbi/api/v4/serviceSpecification/{uuid}/specificationInputSchema``
170 It is use to retrieve one input schema from the tosca file stored in **NBI**
171 - all available information are retrieved (see Swagger for description)
173 **POST service Specification**
177 ``POST /nbi/api/v4/serviceSpecification``
179 This operation creates a ``serviceSpecification`` in catalog (see Swagger for description)
180 It is used to provide a consistent way of on-boarding third party services to SDC via External API
182 Only *primitive type* service characteristics are supported as part of this release. Further enhancements
183 need to be made on other modules of ONAP for ensuring e2e automation of third party services.
189 This API is based from TMF638 serviceInventory. Only high level information
190 is provided - Swagger is documented.
192 This API retrieves service(s) in the **A&AI** inventory. Only following
193 attributes will be retrieve in service inventory: ``id``, ``name``, ``state``
196 **GET Service Inventory (list)**
198 Example: ``GET /nbi/api/v4/service/?relatedParty.id=Pontus``
200 GET (by list) allows to request with following criteria (all optional) :
202 * ``id`` (id of the service instance) - id of the service instance
204 * ``serviceSpecification.id`` - id of the service specification (catalog)
205 * ``serviceSpecification.name`` - name of the service specification (catalog)
206 * ``relatedParty.id`` - id of the (**A&AI**) customer - if not filled we use
209 if no service matches, an empty list is send back.
211 1. If a request is send without any parameter, we'll retrieve the list of
212 service-instance for the *generic* customer
213 2. If only customer parameter is filled (``relatedParty.id`` +
214 role= relatedParty'ONAPcustomer') we'll retrieve the list of
215 service-instance for this customer
216 3. If serviceSpecification.id or name is filled we'll retrieve the list of
217 Service instance (from this service specification) - We'll use the customer
218 id if provided (with Role='ONAPcustomer) or generic if no customer id
221 **GET Service Inventory (id)**
223 Example: ``GET /nbi/api/v4/service/{id}`` When querying for a specific service
224 instance id, no additional filters are required.
226 The Service Inventory API will retrieve the service instance data from A&AI
227 using the nodes query with the service instance id as the key.
228 ``relatedParty.id`` + ``serviceSpecification.name`` are added to the response
229 based on the A&AI service instance url.
235 This API is based from TMF641 serviceOrder. Only high level information
236 is provided - Swagger is documented.
238 It is possible to use POST operation to create new ``serviceOrder`` in **NBI**
239 and triggers service provisioning. GET operation is also available to retrieve
240 one service order by providing id or a list of service order. For this release,
241 only a subset of criteria is available:
246 * ``orderDate.gt`` (orderDate must be greater - after -than)
247 * ``orderDate.lt`` (orderDate must be lower-before - than)
248 * ``fields`` - attribute used to filter retrieved attributes (if needed) and
250 * ``offset`` and ``limit`` are used for pagination purpose
252 ServiceOrder will manage following ``actionItem`` action:
254 * ``add`` - a new service will be created
255 * ``delete`` - an existing service will be deleted
256 * ``change`` - an existing service will be deleted and then created with new
259 **Prerequisites & assumptions**
261 * Cloud & tenant information MUST BE defined in the external API property file
262 * Management of ONAP customer for add service action
264 With the current version of APIs used from **SO** and **A&AI** we need to
265 manage a *customer*. This customer concept is confusing with Customer BSS
266 concept. We took the following rules to manage the *customer* information:
268 * It could be provided through a ``serviceOrder`` in the service Order a
269 ``relatedParty`` with role ``ONAPcustomer`` should be provided in the
270 ``serviceOrder`` header (we will not consider in this release the party
271 at item level). External API component will check if this customer exists
272 and create it in **A&AI** if not.
273 * If no ``relatedParty`` is provided, the service will be affected to
274 ``generic customer`` (dummy customer) - we assume this ``generic customer``
276 * Additionally **NBI** will create in **A&AI** the service-type if it did not
277 exists for the customer
279 **ServiceOrder management in NBI will support 2 modes:**
281 * E2E integration - **NBI** calls **SO** API to perform an End-To-end
283 * Service-level only integration - **NBI** will trigger only **SO** request at
284 serviceInstance level. **SO** prerequisite: **SO** must be able to find a
285 BPMN to process service fulfillment (integrate VNF, VNF activation in
288 The choice of the mode is done in NBI depending on information retrieved in
289 **SDC**. If the serviceSpecification is within a Category "E2E Service" ,
290 **NBI** will use E2E **SO** API, if not only API at service instance level
293 There is no difference or specific expectation in the service order API used
296 **ServiceOrder tracking**
298 State management: States are only managed by ServiceOrder component and could
299 not be updated from north side via API.
300 Accordingly to service order item fulfillment progress, order item state are
301 updated. Order state is automatically updated based on item state.
302 Additionnally to this state, **NBI** provided a completion percent progress to
303 have detailled information about order progress.
304 Order Message are retrieved in the ``GET serviceOrder`` to provide **NBI** used
305 addtionnal information about ``serviceOrder`` management.
309 It is possible for an external system to subscribe to service order
310 notifications. 3 events are managed:
312 * A new service order is created in **NBI**
313 * A service order state changes
314 * A service order item state changes
316 It is also possible to subscribe to **AAI** and **SDC** notifications via
318 4 events are managed:
320 * A new service is created in **AAI***
321 * A service attribute value is changed in **AAI**
322 * A service is removed in **AAI**
323 * A service specification is distributed in **SDC**
325 These 7 events have distinct notification allowing any system to subscribe to
326 one, two or all notification types.
328 The implementation will be split in 2 components:
330 * A HUB resource must be managed within the NBI/serviceOrder API. This HUB
331 resource allows system to subscribe to **NBI** notification
332 * An Event API must be available at listener side in order to be able to
333 receive Listener (when event occurs). **NBI** will be upgraded to use this
334 API as client - **NBI** will shoot ``POST listener/``
336 The following diagram illustrates such notification flow:
338 .. image:: images/notification.jpg
341 **East-west interaction of ONAP instances through External API**
343 Operator's SO component will talk to service provider's external API component
344 through its own external API component.
346 External API support two methods of posting a Service Order or registering for
349 1. If the incoming request is per current implementation (no additional headers
350 ) then no changes will be made. The request will be serviced per BAU flow.
351 2. If the incoming request has additional *Target* header parameters, External
352 API will identify that the request has to be relayed to another ONAP instance
353 and route the request accordingly.
355 Target parameter: The public endpoint url for target ONAP instance's External
357 http://externalDomain/nbi/api/vX
359 * For posting service order and getting service order status, the request will
360 be relayed to target (service provider's External API) as-is. These are
361 synchronous requests and operator's External API will wait for response from
362 the target and relay it back to original calling system (operator's SO).
363 * For Hub API, there is an additional step required. The listener from calling
364 system (operator's SO) will be replaced with External APIs own listener.
365 A mapping of registered subscriber and its original listener will be
366 maintained in External API's DB. Operator's External API will relay the Hub
367 API call to service provider's External API. The service provider's External
368 API will register operator's External API as a listener.
369 * After SO processing in service provider's ONAP is completed (irrespective of
370 status - reject, success, fail etc), service provider's External API will
371 notify the operator's External API about request completion. Operator's
372 External API will look-up for registered subscriber and its original listener
373 (operator's SO) and relay the message.
375 Operator's Service Orchestrator will invoke its own External API component and
376 add SP Partner URL in the header. After receiving an acknowledgement for
377 Service Order request, the SO component will register with External API's hub
378 and provide its listener for processing callback events.
380 Technical information about **East-west interaction exercise** design
381 specification and API Flow illustration (with example messages) could be found
384 https://wiki.onap.org/download/attachments/8227019/CCVPN%20Phase%202%20HLD.docx?api=v2
391 Technical information about **NBI** (dependencies, configuration, running &
392 testing) could be found here:
393 :doc:`NBI_Developer_Guide <../architecture/NBI_Developer_Guide>`
395 API Flow illustration (with example messages) is described in this document:
396 :download:`nbicallflow.pdf <pdf/nbicallflow.pdf>`