docs/offeredapis/offeredapis.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2018 ORANGE
   4
   5
   6 Offered APIs
   7 ============
   8 ************
   9 Introduction
  10 ************
  11
  12 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**.
  13
  14 *******************************************
  15 Global NBI architecture for Beijing release
  16 *******************************************
  17
  18 Following illustration provides a global view about nbi architecture,integration with other ONAP components and API resource/operation provided.
  19
  20 .. image:: images/ONAP_External_ID_Beijing.jpg
  21    :width: 800px
  22
  23 ***********
  24 API Version
  25 ***********
  26
  27 APIs are described with a  state version with “v” following the API Name, e.g.:  nbi/api/v1/productOrder.
  28 The schema associated with a REST API must have its version number aligned with that of the REST API.
  29
  30 The version number has major, minor and revision numbers. E.g. v1.0.0
  31 The version number (without the revision number) is held in the URI.
  32
  33 The major version number is incremented for an incompatible change.
  34 The minor version number is incremented for a compatible change.
  35 For minor modifications of the API, version numbering must not be updated, provided the following  backward compatibility rules are respected:
  36
  37 - New elements in a data type must be optional (minOccurs=0)
  38 - Changes in the cardinality of an attribute in a data type must be from mandatory to optional or from lower to greater
  39 - New attributes defined in an element must be optional (absence of use=”required”).
  40 - If new enumerated values are included, the former ones and its meaning must be kept.
  41 - If new operations are added, the existing operations must be kept
  42 - New parameters added to existing operations must be optional and existing parameters
  43 must be kept
  44
  45 For major modifications of the API, not backward compatible and forcing client implementations to be changed, the version number must be updated.
  46
  47 *********
  48 API Table
  49 *********
  50
  51 .. |pdf-icon| image:: images/pdf.png
  52               :width: 40px
  53
  54 .. |swagger-icon| image:: images/swagger.png
  55                   :width: 40px
  56
  57
  58 .. |swaggerUI-icon| image:: images/swaggerUI.png
  59                     :width: 40px
  60
  61 .. |html-icon| image:: images/html.png
  62                :width: 40px
  63
  64 .. |plantuml-icon| image:: images/uml.jpg
  65                   :width: 40px
  66
  67 .. |postman-icon| image:: images/postman.png
  68                   :width: 40px
  69
  70 .. csv-table::
  71    :header: "API", "|swagger-icon|", "|html-icon|", "|plantuml-icon|", "|swagger-icon|", "|postman-icon|", "|pdf-icon|"
  72    :widths: 10,5,5,5,5,5,5
  73
  74    " ", "json file", "html doc", "plantUML doc", "Swagger Editor", "Postman Collection", "pdf doc"
  75    "serviceCatalog", ":download:`link <swaggers/serviceCatalog_1_0_0.json>`", ":download:`link <serviceCatalog/documentation.html>`", ":download:`link <serviceCatalog/apiServiceCatalog.plantuml>`", "coming", "coming", "coming"
  76    "serviceInventory", ":download:`link <swaggers/serviceInventory_1_0_0.json>`", ":download:`link <serviceInventory/documentation.html>`", ":download:`link <serviceInventory/apiServiceInventory.plantuml>`", "coming", "coming", "coming"
  77    "serviceOrder", ":download:`link <swaggers/serviceOrder_1_0_0.json>`", ":download:`link <serviceOrder/documentation.html>`", ":download:`link <serviceOrder/apiServiceOrder.plantuml>`", "coming", ":download:`link <postman/ONAPBeijingServiceOrderDoc.postman_collection.json>`", "coming"
  78
  79
  80 ***************
  81 API Description
  82 ***************
  83
  84 **serviceCatalog:**
  85
  86 From TMF633 serviceCatalog
  87
  88 API at a glance:
  89 Only high level information are provided - swagger is documented.
  90
  91 Only serviceSpecification resource is provided.
  92 Information are retrieved in SDC (and in Tosca file) - Only GET operation is provided - this API DID NOT UPDATE SDC
  93
  94 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.
  95
  96 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
  97
  98
  99 GET serviceSpecification(list)
 100
 101 (example: GET /nbi/api/v1/serviceSpecification/?category=NetworkService&distributionStatus =DISTRIBUTED)
 102
 103 It is possible to retrieve a list of serviceSpecification (get by list).
 104
 105 Only attributes category and distributionStatus are available for serviceSpecification filtering. It is possible to select retrieved attributes using fields attribute.
 106
 107 if no serviceSpecification matches, an empty list is send back.
 108
 109 GET service Specification (id)
 110
 111 (example: GET /nbi/api/v1/serviceSpecification/{uuid})
 112
 113 It is use to retrieve one serviceSpecification - all available information are retieved (see swagger for description)
 114
 115
 116 **serviceInventory:**
 117
 118 From TMF638 serviceInventory
 119
 120 API at a glance:
 121 Only high level information are provided - swagger is documented.
 122
 123 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 )
 124
 125 GET Service Inventory (list):
 126
 127 (example: GET /nbi/api/v1/service/?relatedParty.id=Pontus
 128 )
 129
 130 GET (by list) allows to request with following criteria (all optional) :
 131
 132 *   id (id of the service instance) - id of the service instance (inventory)
 133 *   serviceSpecification.id - id of the service specification (catalog)
 134 *   serviceSpecification.name - name of the service specification (catalog)
 135 *   relatedParty.id - id of the (aai) customer - if not filled we use ‘generic’ customer
 136
 137 if no service matches, an empty list is send back.
 138
 139 1.      If a request is send without any parameter, we’ll retrieve the list of service-instance for the ‘generic’ customer
 140 2.      If only customer parameter is filled (relatedParty.id + role= relatedParty’ONAPcustomer’) we’ll retrieve the list of service-instance for this customer
 141 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
 142
 143
 144 GET Service Inventory (id):
 145
 146 (example: GET /nbi/api/v1/service/{uuid} but customerId & serviceSpecification.id must passed in requested parameters)
 147
 148
 149 Because of AAI capability, additionally to the service id, customer id and [serviceSpecification.id or serviceSpecification.name] must be supplied. If the customer id is not supplied, External API will use ‘generic’ customer
 150
 151 **serviceOrder:**
 152
 153
 154 From TMF641 serviceOrder
 155
 156 API at a glance:
 157 Only high level information are provided - swagger is documented.
 158
 159 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:
 160
 161 •     externalId
 162 •     state
 163 •     description
 164 •     orderDate.gt (orderDate must be greater – after -than)
 165 •     orderDate.lt (orderDate must be lower-before - than)
 166 •     fields – attribute used to filter retrieved attributes (if needed) and also for sorted SO
 167 •     offset and limit are used for pagination purpose
 168
 169
 170
 171 ServiceOrder will manage only ‘add’ and ‘delete’ operation (no change).
 172
 173 prerequisites & assumptions :
 174
 175 •     Cloud & tenant information MUST BE defined in the external API property file
 176 •     Management of ONAP customer for add service action:
 177 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:
 178
 179 •     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.
 180 •     If no relatedParty are provided the service will be affected to ‘generic’ customer (dummy customer) – we assume this ‘generic’ customer always exists.
 181
 182 •     Additionally nbi will create in AAI the service-type if it did not exists for the customer
 183
 184 •     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
 185
 186 •     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.
 187
 188
 189 ********
 190 API flow
 191 ********
 192
 193 API Flow illustration (with example messages) is described in this document: :download:`nbicallflow.pdf <pdf/nbicallflow.pdf>`
 194