Common Versioning Architecture Team

Dan Timoney's Proposal for RESTCONF API

We discussed Dan's proposal and it has been accepted. Dana Bobko will move to the API CVS wiki page.

ICYMI - here is the proposal:

The URI format above does not fit well for controllers based on OpenDaylight - or more generally, for controllers that expose RESTCONF interfaces. There are existing conventions in RESTCONF that are built in to OpenDaylight (and probably other controller platforms as well) that could make it difficult to meet the URI standards above exactly, but we can get fairly close.

In RESTCONF, APIs are organized by "modules", which for our purposes we can say are analogous to services.  There are 3 different types of APIs, each with its own standard URI format:

• Configuration data (also referred to as "config tree"), which stores the in flight view of network data (so it shows pending changes).
  • Required URI is  /restconf/config/{module}/{resource} 
• Operational data (also referred to as the operational tree), which stores the current active view of network data.  
  • Required URI is /restconf/operational/{module}/{resource}
• RPCs
  • Required URI is /restconf/operational/{module}/{rpc name}

I propose the following conventions for versioned RESTCONF APIs for ONAP:

• Configuration data: /restconf/config/{service}:v{version}_{resource}  e.g. /restconf/config/neutron:v2_networks
• Operational tree : /restconf/operational/{service}:v{version}_{resource} e.g. /restconf/operational/neutron:v2_networks
• RPC : /restconf/operations/{service}:v{version}_{rpc} e.g. /restconf/operations/SLI-API:v1_healthcheck

This is fairly close to the proposed standard, with the exception that the separator between version and resource is an underbar instead of a slash.

If this is not acceptable, then SDNC and APPC will need to change their architecture to route through some form of proxy (e.g. apache) whose only purpose is to rewrite the URL, which seems inefficient and error prone.

Gregory Glover and Dana Bobko will present to the TSC, including the proposal above.

This is the next on the priority list for versioning. SDC models already have a versioning methodology; therefore, we need to understand better how it is accomplished today. Dana Bobko will find a contact from SDC to provide this information.

UPDATE (6/18/2018)

• SDC minor versions are not BWC. 
• As a model goes through different phases (testing, other changes), the MINOR position increments.
• The MAJOR increments once the certification has been completed.
• Anatoly will send Dana a copy of the SDC AID.

SDC Distributed Model Versioning Information

• A minor version indicates that the element is In Design. When you create an ASDC element (VSP, VF, or Service), it starts at version 0.1. When you choose to check it in, it will remain at 0.1. When you choose to check it out, the minor version will increment by 0.1.
  • For a VSP, the version will increment to a whole number when it is checked in and submitted.
  • For a VF and a Service, the version will increment to a whole number when it is certified by a tester.
  • If a VSP, VF, and Service is checked out after reaching a whole number (VSP is submitted or VF/Service is certified by a tester), it increases by 0.1.
• Check out may be canceled so the version does not increment. You can cancel a check out by clicking on the trash can at the top right side of the screen. You’ll get a warning message to confirm that you want to delete this version – yes, you do. When you delete, the model will return to the check-in state and the version will return to what it was prior to your checkout.

Note: If you don’t need to modify a service, resource, VSP, or Vendor License Model (VLM), don’t check it out. You can see all of the settings and download all of the artifacts without checking out.
VSP = Vendor Software Product. It is the foundation of a VF. The VSP is where the designer uploads the heat zip and associates the vendor license model (VLM). VSPs are found in the ONBOARD section of the GUI.

In VNF descriptor for onboarding, there might be some value add in exposing revisions of classes or class types; possibly tie in with data dictionary.

Andy Mayer suggested a quick call with Anatoly Katzman for us to gain a better understanding. Dana will setup the call prior to our next meeting. 

UPDATE (6/18/2018)

We met with Anatoly and he agrees there is some value in exposing the revisions of classes or class types.

• There are some gaps in modeling versions that are being worked out.
• If you open a CSAR, there are two types generated:
• GLOBAL - no versioning present.
• (Artificially) LOCAL - versioning is already present; has a MAJOR.MINOR that "looks" like semver; however, not really semver (no PATCH). The ONAP Modeling Project is driving the versioning of LOCAL types.
• API version is more of a factor versus the model version, not really BWC.
• Dana Bobko will follow-up with John Choma and Chesla Weschler on how the SO model is versioned.  

UPDATE (8/7/2018)

Dana met with the Modeling Subcommittee today. Expected response in a few days after members have had a chance to review this. They have been asked to comment on the versioning for items 2 and 3 below (in red) in the prioritization of entities for the versioning strategy.

UPDATE 8/21/2018

Feedback from Anatoly:

The SDC  team is also publishing an abridged version of the ASDC TOSCA AID document for the ONAP forum:

https://wiki.onap.org/display/DW/SDC+Data+model

and

https://wiki.onap.org/display/DW/ONAP+SDC+AID+Data+Model 

Chris Donley would like to pull together a deck to present to the TSC in Vancouver (5/23/2018) to get CVS priorities on the Plan of Record. Need to finalize any feedback/concerns, prior to the Casablanca planning. Casablanca planning occurs at the end of June