Wire protocol options clarification

[italobusi]

During the TAPI call on September 18, 2018, it was not clear whether an implementation using TAPI OpenAPI specification and another implementation using TAPI RESTCONF/YANG would be compatible on the "wire-protocol"

My understanding is that ONF is not going to constraint the wire-protocol options and that some a-priori agreements is needed by TAPI client and server implementations to ensure wire-protocol interoperability

It is worthwhile adding some clarification text to the TAPI 2.1 release notes

[italobusi]

Initial proposed text for TAPI 2.1 release note:

ONF TAPI R2.1 definitions do not constraint any “wire protocol” implementation choice, so different, and possibly incompatible, implementation options can be supported by compliant implementations:

• RESTCONF based on delivered TAPI R2.1 YANG model
• OpenAPI based on delivered TAPI R2.1 OpenAPI specification
• RESTCONF based on a YANG model generated from the TAPI R2.1 UML model manually or with another tool (e.g., a newer version)
• OpenAPI based on a specification generated from TAPI R2.1 YANG model manually or with another tool

TAPI client and server implementations shall agree a-priori a common “wire protocol” specification (e..g, via an Implementation Agreement) to ensure interoperability

[italobusi]

During the TAPI call it has been agreed that TAPI Yang model released as part of an official TAPI release is the only valid TAPI YANG model for that release, while TAPI UML model released as part of an official TAPI release is the only source of subsequent generated (YANG, OAS, etc) TAPI deliverable outputs.

Updated text proposal for TAPI 2.1 release notes:

ONF TAPI YANG model released as part of an official TAPI release is the only valid TAPI YANG model for that release ONF does not constraint any “wire protocol” implementation choice based on the released YANG model. Different, and possibly incompatible, implementation options can be supported by compliant implementations, such as:

• RESTCONF/YANG based on released TAPI R2.1 YANG model
• OpenAPI based on release TAPI R2.1 OpenAPI specification
• Any other RESTful APIs as long as they are based on the release TAPI R2.1 YANG models

TAPI client and server implementations shall agree a-priori a common “wire protocol” specification (e..g, via an Implementation Agreement) to ensure interoperability

[karthik-sethuraman]

As per the TAPI call on 10/2/18 (https://wiki.opennetworking.org/display/OTCC/2018-10-02+TAPI+Meeting+Notes), I would propose the following concise text (no point including redundant text)

- TAPI UML model released as part of an official TAPI release is the only source of subsequent generated (YANG, OAS, etc) TAPI deliverable outputs.
- TAPI Yang model released as part of an official TAPI release is the only valid TAPI YANG model for for that release.
-- This specification is generated using the IISOMI UML2YANG mapping guidelines (https://wiki.opennetworking.org/display/OIMT/UML+-+YANG+Guidelines) by the ONF EAGLE tool from the official UML model for that release.
- TAPI OAS (OpenAPI spec) released as part of an official TAPI release is the recommended REST API specification for that TAPI release
-- This specification is generated using RESTConf guidelines (https://tools.ietf.org/html/rfc8040) as by the ONF EAGLE tool from the official TAPI YANG model for that release
-- Implementations may use other flavors of RESTConf/RESTful APIs as long as they are based on the released TAPI R2.1 YANG models and have an implementation agreement between concerned parties to do so.

[italobusi]

I do not think we have agreed on the statements regarding OpenAPI

The current text is ambiguous and potentially misleading: see also open issue #360