NBI API Description

Introduction

OSM North Bound Interface is a REST-full following ETSI SOL005 standard. It admits both YAML/JSON formats.

By default it serves https (auto-signed certificate) on port 9999. Bearer authentication (with token) is used. Basic authentication or no authentication is also possible changing 'nbi.cfg' file.

For developping porpouses it admits web browser navigation using a basic http format.

Request headers

Accept: 'application/json','application/yaml' in most of the cases. Use 'text/html' for web navigation. Use 'text/plain','application/zip' for descriptor artifacts showing. This header field shall be present if the response is expected to have a non-empty message body.

Content-Type: 'application/json','application/yaml' for most of the cases. For packages uploading use 'application/gzip','application/zip','application/x-gzip','application/binary'. For descriptor artifacts it can be used 'text/plain'. This header field shall be present if the request has a non-empty message body.

Authorization: 'Bearer <token_id>'. The authorization token for the request. It is mandatory except when a token is requested.

Content-Range: '<first byte>-<last byte>0/<total>'. It allows uploading a descriptor by chunks.

Transaction-Id: '<id>'. When uploaded by chunk, the id returned by first chunk

Content-File-MD5: '<md5>'. MD5 of uploaded package.

Content-Filename: '<filename>'. Filename of the uploaded package.

Query-String-Format: '<yaml>'. Parses query string values using yaml format.

Response headers

Content-Type: 'application/json','application/yaml' is the more normal. 'text/html' when web navigation. 'application/gzip','text/plain' for descriptor artifacts

Location: '/<main_topic>/v1/<topic>/<id>'. Always that something is created, this header is present containing URL to this element.

WWW-Authenticate: 'Bearer realm="{}"'. When Authentication error is obtained.

Retry-After: ''. (Future releases)

Query string

Query string has the format: '?key=value&key2=value2&...'.

Some special keys are:

• FORMAT=True Forces and operation. It disables descriptor checkings, dependency cheking. For delete, it allows deleting things that cannot done in normal operation because dependency. But beware that forcing deletion will not deletes created things at VIM level.

For GET method it allows filtering with this format, follows SOL005 section 4.3.2:

query string := ?<simpleFilterExpr>["&"<simpleFilterExpr>]*
simpleFilterExpr := <attrName>["."<attrName>]*["."<op>]"="<value>[","<value>]*
op := "eq" | "neq" (or "ne") | "gt" | "lt" | "gte" | "lte" | "cont" | "ncont"
   equal (by default), not equal, greater than, less than, greater than or equal, less than or equal, contains, not contains
attrName := string. For filtering inside array, use the index element of the array, or add ANYINDEX to apply the filtering over the same array element

For PUT/POST/PATCH It allows override e.g. package content, with the values of this query string

URL and Methods summary

North Bound Interface (O: OSM specific; X,5: SOL005 not OSM implemented yet; O5: OSM and SOL005)

URL: /osm                                                       GET     POST    PUT     DELETE  PATCH
        /nsd/v1
            /ns_descriptors_content                             O       O
                /<nsdInfoId>                                    O       O       O       O
            /ns_descriptors                                     O5      O5
                /<nsdInfoId>                                    O5                      O5      5
                    /nsd_content                                O5              O5
                    /nsd                                        O
                    /artifacts[/<artifactPath>]                 O
            /pnf_descriptors                                    5       5
                /<pnfdInfoId>                                   5                       5       5
                    /pnfd_content                               5               5

        /vnfpkgm/v1
            /vnf_packages_content                               O       O
                /<vnfPkgId>                                     O                       O
            /vnf_packages                                       O5      O5
                /<vnfPkgId>                                     O5                      O5      5
                    /package_content                            O5               O5
                        /upload_from_uri                                X
                    /vnfd                                       O5
                    /artifacts[/<artifactPath>]                 O5

        /nslcm/v1
            /ns_instances_content                               O       O
                /<nsInstanceId>                                 O                       O
            /ns_instances                                       5       5
                /<nsInstanceId>                                 O5                      O5
                    instantiate                                         O5
                    terminate                                           O5
                    action                                              O
                    scale                                               O5
                    heal                                                5
            /ns_lcm_op_occs                                     5       5
                /<nsLcmOpOccId>                                 5                       5       5
                    TO BE COMPLETED                             5               5
            /vnf_instances  (also vnfrs for compatibility)      O
                /<vnfInstanceId>                                O

        /pdu/v1
            /pdu_descriptor                                     O       O
                /<id>                                           O               O       O       O

        /admin/v1
            /tokens                                             O       O
                /<id>                                           O                       O
            /users                                              O       O
                /<id>                                           O               O       O       O
            /projects                                           O       O
                /<id>                                           O                       O
            /vim_accounts  (also vims for compatibility)        O       O
                /<id>                                           O                       O       O
            /wim_accounts                                       O       O
                /<id>                                           O                       O       O
            /sdns                                               O       O
                /<id>                                           O                       O       O

        /nst/v1                                                 O       O
            /netslice_templates_content                         O       O
                /<nstInfoId>                                    O       O       O       O
            /netslice_templates                                 O       O
                /<nstInfoId>                                    O                       O       O
                    /nst_content                                O               O
                    /nst                                        O
                    /artifacts[/<artifactPath>]                 O

        /nsilcm/v1
            /netslice_instances_content                         O       O
                /<SliceInstanceId>                              O                       O
            /netslice_instances                                 O       O
                /<SliceInstanceId>                              O                       O
                    instantiate                                         O
                    terminate                                           O
                    action                                              O
            /nsi_lcm_op_occs                                    O       O
                /<nsiLcmOpOccId>                                O                       O       O

Administrative Content Details

/admin/v1/tokens. Token is a temporal authorization for a user in a project

• GET: Get tokens
• POST: Obtain a token. The username, password and optional project is needed. If project is not suplyed it asign first project of available for this user.
  • Example of request content: '{username: <user>, password: <pass>, project_id: <project>}'

/admin/v1/tokens/<id>

• GET: show token details
• DELETE: revoque token. Logout

/admin/v1/users. Users may operate in several projects

• GET: Get users
• POST: Add a new user.
  • Example of request content: TODO

/admin/v1/users/<id>

• GET: Get user details
• PUT/PATCH: Edit user.
  • Example of user edition: TODO
• DELETE: Removes user.

/admin/v1/projects. A project contains its own separate space

• GET: Get projects
• POST: Add a new projects.
  • Example of request content: TODO

/admin/v1/projects/<id>

• GET: Get project details
• PUT/PATCH: Edit project.
  • Example of project edition: TODO
• DELETE: Removes project.

/admin/v1/vim_accounts. Vim account is the deployment target

• GET: Get vim_accounts
• POST: Add a new vim_accounts.
  • Example of request content: TODO

/admin/v1/vim_accounts/<id>

• GET: Get vim_account details
• PUT/PATCH: Edit vim_account.
  • Example of vim_account edition: TODO
• DELETE: Removes vim_account.

/admin/v1/wim_accounts. WIM are WAN Infrastructure Managers, that is in charge of inter VIM connectivity managemnt

• GET: Get wim_accounts
• POST: Add a new wim_account.
  • Example of request content: TODO

/admin/v1/wim_accounts/<id>

• GET: Get wim_account details
• PUT/PATCH: Edit wim_account.
  • Example of wim_account edition: TODO
• DELETE: Removes wim_account.

/admin/v1/sdns. SDN controllers in charge of VIM underlayed connectivity

• GET: Get sdns
• POST: Add a new sdn.
  • Example of request content: TODO

/admin/v1/sdns/<id>

• GET: Get sdn details
• PUT/PATCH: Edit sdn.
  • Example of sdn edition: TODO
• DELETE: Removes sdn.

PDU Details

Physical Data Unit. This is catalogue of physical elements present at some vim_account/s. Deployment of a PNFD/HNFD implies using one of this pdu from the catalogue. Matching from PNFD/HNFD to PDU is done by 'pdu.type'

/pdu/v1/pdu_descriptor

• GET: List PDUs. Use query string for filtering.
• POST: Create a new PDU.
  • Example of request content:

name: descriptive name              # mandatory
type: str                           # mandatory. maps VNFD.vdu.pdu-type
description: str
vim_accounts: [vim-account-id, ...] # mandatory
interfaces:                         # mandatory
-   name: str                       # mandatory. Maps VNFD.vdu.interfaces.name
    mgmt: boolean                   # mandatory. Indicates if is the management one
    ip-address: ip                  # mandatory
    vim-network-id: xxx                 
    vim-network-name: xxx                

/pdu/v1/pdu_descriptor/<id>

• GET: show PDU details
• PUT: overwrite this PDU
• PATCH: edit this PDU
• DELETE: remove the PDU

VNFD Details

Virtual Network Function Descriptor. This includes also Physical and Hybrid Network Funcitons Descriptors (PNFD/HNFD). (At VDU level, it is indicated if it is physical with the 'pdu-type' information element).

TBC

NSD Details

Network Services Descriptor

TBC

NSLCM Details

Network Services Life Ciclo Management

TBC

NST Details

NetSlice Template descriptor

TBC

NSILCM Details

NetSlice Instance Life Ciclo Management

TBC