SOL OpenAPI Main Page

From NFVwiki
Revision as of 12:43, 30 August 2019 by Chatras (talk | contribs) (Created page with "= OpenAPI Development Guidelines = == Governance == === Usage of the ETSI Forge Repositories === The current available ETSI Forge Repositories are: * [https://forge.etsi.o...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

OpenAPI Development Guidelines

Governance

Usage of the ETSI Forge Repositories

The current available ETSI Forge Repositories are:

The development of a new version of OpenAPI representation for a given SOL version x.y.z specification need to follow this procedure:

  1. Create a new branch from "master", and name it "x.y.z-dev"
  2. Develop the OpenAPI representations for version x.y.z in the new branch "x.y.z-dev"
  3. When a final version of the OpenAPI representations is ready, create a tag on the "x.y.z-dev" branch with name "x.y.z-dev-final-version"
  4. Request for SOL WG approval for the OpenAPI representations available at the tag "x.y.z-dev-final-version"
  5. Apply any required fix related to issues found during the approval period
  6. When done, create a tag on the "x.y.z-dev" branch with name "x.y.z-dev-final-version-approved"
  7. Apply a merge request to master branch
  8. Create a tag on the "master" branch with name "x.y.z"

Roles and Responsibilities

A definition of roles and responsibilities for OpenAPI governance is needed to ensure:

  • Comments on the OpenAPIs can be reported
  • Categorization of the comments
  • Timeliness for resolving OpenAPI comments
  • Accountability (who is responsible for resolving)
  • Provide added value for the consumers of ETSI NFV API specifications and foster adoption
SOL00x Project Lead Responsibilities SOL00x Project Delegate Responsibilities
1. Review OpenAPI comments 1. Same as SOL00x project lead
2. Ensure consistency between the Stage 3 ETSI-GS and the OpenAPI representation(s) 2. Same as SOL00x project lead
3. Propose resolution to the comments sent to the SOL API mailing list within 3 business days to work towards achieving consensus 3. Propose resolution to the comments in concert with the SOL00x project lead
4. Provide status/feedback to the reporter of the comment 4. Same as SOL00x project lead (at the discretion of the SOL00x project lead)
5. Update the OpenAPI for Category 1, 2, and 4 comments 5. Same as SOL00x project lead (at the discretion of the SOL00x project lead)
SOL Document OpenAPI Project Lead OpenAPI Delegate
SOL002 v2.4.1, v2.5.1, v2.6.1, v3.3.1 STF 563 Experts STF 563 Steering Committee
SOL003 v2.4.1, v2.5.1, v2.6.1, v3.3.1 STF 563 Experts STF 563 Steering Committee
SOL005 v2.4.1, v2.5.1, v2.6.1, v3.3.1 STF 563 Experts STF 563 Steering Committee

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:

  • Log in at the Forge (at https://forge.etsi.org/index.php/users/login )
  • Navigate to the new issue page.
  • Choose the relevant affected OpenAPI specification
  • Fill in the information for the issue
    • Please choose the proper category for the issue
  • Click the “Submit Comment” button

The current OpenAPI issue list is available here.

OpenAPI Representations

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

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