SOL OpenAPI Main Page

From NFVwiki
Revision as of 08:24, 26 August 2020 by Chatras (talk | contribs) (→‎Report issues and feedbacks to OpenAPIs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

OpenAPI Representations

The full list of available SOL OpenAPI representations is available here.

OpenAPI Development Guidelines

General development guidelines

NFV SOL Common APIs are described using the OpenAPI language version 2. Click here to find the official reference.

Definitions

Definitions referenced from multiple locations in a specification shall be put into separate files.

Resources

If the number of resources in specification is large then the total set of resources may be split over several files.

Usage of IDEs

The development of OpenAPI representations does not require any specific IDE (Integrated Development Environment).

However, the STF 563 experts used the IntelliJ IDE with a Swagger plugin:

These tools ease the development of the OpenAPI representations, by offering a set of useful features:

  • autocompletion of keywords
  • detection of syntax errors
  • detection of wrong paths
  • unused datatype highlight
  • automated formatting

OpenAPIs versioning

Terminology

Term Description
API version identifier Identifies the version of the OpenAPI description of an API.
GS version number Identifies the version of an ETSI Group Specification.
Base GS Identifies the ETSI GS that contains the reference specification of an API.

Structure of API version identifiers

API version identifiers shall consist of 3 numerical fields (as defined in ETSI GS NFV-SOL 013), following a MAJOR.MINOR.PATCH pattern and the rules for Semantic Versioning.

The fields in an API version identifier shall be separated by dots ".".

The last field may be followed by one or more version parameters. The MAJOR, MINOR and PATCH fields are defined according to the Semantic Versioning.

The {apiMajorVersion} segment of the URIs used by an API shall be set to the character "v" followed by value of the MAJOR field of the API version identifier.

Example: 

.../vnflcm/v1/

Rules for incrementing field values

According to ETSI GS NFV-SOL 013, Different criteria are applied to increment MAJOR, MINOR, and PATCH version fields for changes that affect the URI compared to changes that affect the payload body.

The fields of an API version identifier are incremented from a previous version to the current version according to the rules defined in clause 9.2 of ETSI GS NFV-SOL 013.

Visibility of the API version identifier fields in the OpenAPI specifications

According to ETSI GS NFV-SOL 013, the resource URI prefix of every API is structured as follows: 

{apiRoot}/{apiName}/{apiMajorVersion}/

where apiMajorVersion is the concatenation of the letter “v” and the "MAJOR" field of the version identifier. The "MINOR" and "PATCH" fields are not be included in the resource URI.

The full API version identifier (as defined in ETSI GS NFV-SOL 013 and reported above) shall be visible in the OpenAPI specifications, in the “version” subfield of the “info” field, as illustrated in the example below.

The "impl" parameter shall be used to signal the version of the OpenAPI representation of the API, using the following structure: 

etsi.org:ETSI_NFV_OpenAPI:<impl_version>

where <impl_version> is a number.

As an example: 

swagger: "2.0"
info:
  version: "1.2.0-impl:etsi.org:ETSI_NFV_OpenAPI:1"
  title: SOL003 – VNF LCM interface
  license:
    name: "ETSI Forge copyright notice"
    url: https://forge.etsi.org/etsi-forge-copyright-notice.txt
basePath: "/vnflcm/v1"
...

Link to the related base GS version from the OpenAPI specifications

There is no one-to-one mapping between an API version identifier and the version identifier of its base SOL GS.

A GS specifies multiple APIs, which may have different versions.

A change in the 3rd field of a GS version identifier (i.e. an editorial change) does not lead to a change in the version identifiers of the APIs specified in the GS.

A change in the 1st and 2nd fields of the GS version identifier (i.e. a technical change) is likely to lead to at least a change in the minor version number of one of the APIs specified in the GS, which is documented in the definition of the applicable API version in the GS.

For example, if version 2.4.1 of a base GS contains version 1.1.1 of API A, B and C, version 3.1.1 of this base GS can contain version 1.2.1 of API A, version 2.1.1 of API B and version 1.1.1 of API C (if no changes were made to API C). Each OpenAPI specification shall provide in an “externalDoc” field the reference of the base GS, including the version identifier, as illustrated below. 

swagger: "2.0"
info:
  version: "1.2.0-impl:etsi.org:ETSI_NFV_OpenAPI:1"
  title: SOL003 - VNF LCM interface
  description: The VNF LCM API provide access to VNF lifecycle management services
  license:
    name: "ETSI Forge copyright notice"
    url: https://forge.etsi.org/etsi-forge-copyright-notice.txt
externalDocs:
  description: ETSI GS NFV-SOL 003 V2.5.1
  url: https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/003/02.05.01_60/gs_nfv-sol003v020501p.pdf
basePath: "/vnflcm/v1"

Multiple versions of the same GS can contain the same API (e.g., SOL003 VNF LCM API) without any modification. In this case, all GS versions supporting the same API should be listed in the “description” subfield under "externalDocs", and the "url" subfield should point to the latest version of the specification

Folder structure and file names

Repository structure

repository_root
|- src
  |- Deliverable1
    |- Interface1
      |- Interface1.yaml                    Main OAS file
        |- definitions
          | - DataType1.yaml
          | - DataType2.yaml
        |- resources
          | - Resource1.yaml
          | - Resource2.yaml
    |- Interface2
      |- ...
    |- definitions
      | - DataTypeA.yaml
      | - DataTypeB.yaml
    |- resources
      | - ResourceA.yaml
      | - ResourceB.yaml
    | - responses
      | - Responses1.yaml
  |- Deliverable2
    |- Interface3
      |- ...
  |- definitions
    | - DataTypeN.yaml
    | - DataTypeM.yaml
  |- resources
    | - ResourceN.yaml
    | - ResourceM.yaml
  | - responses
    | - Responses.yaml
|- Readme.md
|- LICENSE

File names

  • For each interface, use the name as a root document, eg
   VNFConfiguration.yaml
  • For responses:
   VnfConfiguration_resp.yaml
  • For datatypes:
   VnfConfiguration_def.yaml

Both CamelCase or underscores (_) are available for word separations.

How to Contribute

Report issues and feedbacks to OpenAPIs

In case issues or bugs are found on the OpenAPIs, the user should follow this procedure:

Retrieved from "https://nfvwiki.etsi.org/index.php?title=SOL_OpenAPI_Main_Page&oldid=3660"