OpenAPI versus RESTCONF/YANG API

[italobusi]

As discussed in previous TAPI calls the relationship between OpenAPI and RESTCONF/YANG APIs is not fully clear: more clarification is needed also to write correct statements in the TAPI 2.1 release note (see open issue #359)

[italobusi]

It has been claimed that OpenAPI specification is RESTFUL (RFC8040) compliant but interoperability with any RESTFUL/YANG implementations not using OpenAPI is not ensured

One argument is that RFC8040 is ambiguous and open to different interpretations leading to non-interoperable implementations but no list (even partial) of items where RFC8040 is ambiguous has been provided

Talking with RESTCONF experts, the feedbacks I have got is that, once RFC8040 is implemented, the YANG model is sufficient to fully specify the RESTCONF/YANG wire-protocol

[italobusi]

I think there are three possible cases:

1) OpenAPI specification is compliant and interoperable with RESTCONF (RFC8040)

In this case, the OpenAPI specification is useless and potentially harmful (since ONF is not taking commitment that the EAGLE tool is bug-free)

Therefore, it would be safer not to include any OpenAPI specification in TAPI 2.1 release

The EAGLE tool is just another YANG tool that people may decide to use as part of toolchain that assist their development process

2) OpenAPI specification is intended to be compliant with RESTCONF (RFC8040) but there is no guaranteed of full compliancy and/or interoperability with other RESTCONF implementations

In this case, I think that the EAGLE tool can claim compliance with RESTCONF but the TAPI release notes should not commit on that so the text I have proposed (claiming that OpenAPI and RESTCONF/YANG wire-protocol implementations are "possibly incompatible") seems factual since we do not know whether these two options would lead to compatible or incompatible wire-protocol implementations

3) OpenAPI specification is fully compliant with RESTCONF (RFC8040) but there is no guarantee for full interoperability with other RESTCONF implementations because of some ambiguity in RFC8040

In this case, I think that ONF should provide the list of issues with RFC8040 that justify the need for developing an interpretation and seeks guidance from IETF to check whether these issues are due to lack of understanding or are real issue with RFC8040

4) OpenAPI specification is not fully compliant with RESTCONF (RFC8040) and therefore interoperability with other RESTCONF implementations cannot be guaranteed

Also in this case the text I have proposed seems factual since we still do not know whether these two options would lead to compatible or incompatible wire-protocol implementations

[italobusi]

IETF RFC8040 has been prepared by the Netconf WG:

https://datatracker.ietf.org/wg/netconf/about/

If ONF believes the specification has issues, it would be worthwhile checking with IETF Netconf WG whether they are real issues or misunderstandings

One possibility could be to send a LS from ONF to IETF Netconf WG

Another option could be to send a mail to the WG mailing list (netconf@ietf.org)

The best option would be to submit an Internet-Draft to Netconf WG highlighting the issues that have been identified with RFC8040 and proposing to fix them based on the interpretation assumed during the development of the EAGLE tool

[GermanoSMO]

Based on direct implementation experience, I can confirm Italo's statement:

"once RFC8040 is implemented, the YANG model is sufficient to fully specify the RESTCONF/YANG wire-protocol"

[arthurMll]

In principle I agree with Italo claim: "the YANG model is sufficient to fully specify the RESTCONF/YANG wire-protocol". But any Wire Protocol definition may leads into different interpretantions of the standard and into potentially interoperability issues. The TAPI OAS provides a single Reference Implementation which might be used, as until now, as a common point between parties to achieve interoperability, so there is an inherent value on having it in the TAPI2.1 Release.

IMHO it is on the side of the TAPI consumers (client and server) to agree how TAPI integration is done, either through the ONF proposed OpenAPI specification, or based on the official TAPI YANG model and any other standardized wire protocol for which the YANG definition is sufficient, such RESTCONF RFC 8040 or NETCONF RFC 6241.

But, TAPI 2.1 Relase notes MUST record the fact that TAPI OAS is not officially confirmed as RESTCONF RFC 8040 compliant (because this is not confirmed by IETF Netconf WG) to prevent that someone could argue that any other RESTCONF implementation is not valid becasue it is not compatible with TAPI OAS.

Said this, I think ONF should put efforts on contrasting TAPI OAS RESTCONF (RFC 8040) compliancy (the way to do this should be discussed), given that the objective marked for TAPI 2.1 is having a reference implementation based on RESTCONF.

[arthurMll]

Current Release notes must clarify any ambiguity about the purpose of the TAPI OAS and it must not state compliancy with RESTCONF standard as it is not confirmed.

[demx8as6]

A lot of effort was spent to generate TAPI OAS according to the RestConf RFCs. There is no reason not calling it "compliant". Such discussion does not change anything on TAPI OAS itself. It would be more benefical to start a RestConf certification process and the criterias to pass the certification process.

[arthurMll]

@demx8as6 the point I think is to do not mark TAPI OAS as RESTCONF compliant until the restconf certification process you mention is carried. Which I agree it would be very benefitial for TAPI.

[y-higuchi]

Regarding point about RFC8040 "certification" or "conformance", does IETF or others have a official certification program? e.g. something like CE2.0 certification for MEF specs

If not, any RESTCONF confirming device, controller, etc. out there is pretty much in same situation that they believe to be following RFC8040, isn't it?

Of course, if we already know of a limitation that generated TAPI OpenAPI definition does not conform to RFC8040, then we probably should either note that limitation or not mention RESTCONF at all.

But if we believe it to be aligned with RFC8040 as of the moment, I think the point which needs to be made clear about TAPI OpenAPI released is that: TAPI OpenAPI definition is released as part of TAPI only as a reference, so it is OK for REST client/server implementation not generated from OpenAPI to claim TAPI compatibility, as long as it's based on authoritative information/data model (=released UML/.yang). And I think text proposed in #359 by @karthik-sethuraman covers that concisely.

Note: that RESTCONF ∈ REST API, so RESTCONF is not the only possible way to design REST API.

What do you all think?

[italobusi]

@y-higuchi - You are correct that RESTCONF ∈ REST API

The term REST API does not fully qualify the wire-protocol and therefore some API specification is needed

REST APIs may or may not be based on YANG models

The RESTCONF API is a specific REST API, based on YANG models, which, together with the YANG models, fully qualify the wire-protocol implementation and therefore no API specification is needed in addition to the YANG models

Up to now, RESTCONF is the only standard protocol mechanisms to implement REST API based on YANG models but I am aware that other non-standard mechanisms to implement REST API based on YANG models exist (OpenAPI being one of them)

The key issue that is not clarified with whether OpenAPI = RESTCONF API or not

From the current discussion it seems to me that OpenAPI != RESTCONF API and this should be clearly stated in the release notes because there are many people (including myself at the beginning of this discussion) who have understood the opposite (i.e., OpenAPI = RESTCONF API)

[bartoszm]

Hi, It is fair to say that OpenAPI for TAPIis not 100% aligned with the RFC8040. However this is true for most of the open source and close sourced one of the examples for many years being opendaylight. I think that the yang to OpenAPI transformation tool I am involved in is 90% aligned whereas the pyang based tool was closer to bierman-02 which has some difference in comparison to RFC 8040. Anyways some of the differences between OpenAPI RESTCONF-like definitions and RFC8040 results from:

• conscious decisions: e.g. for TAPI part of resource paths are not generated not to overblown the OpenAPI definition (at the moment path are generated only for resources that inherit from GlobalClass)
• difficulties in mapping between YANG world and OpenAPI world, e.g. pattern expressions are using different specs and cannot be mapped one to other, mapping of augmentation module prefixes for payloads
• lack of time and resources - there is a handful of people working on one or another tool, so some we have a luxury to prioritize features which are the most important for stakeholders.
• and likely from some undiscovered bugs.

I think that if the intention is to have a RESTCONF (RFC 8040) compliant OpenAPI definition for TAPI we could spent some time on identify the inconsistencies and find resources to make these fix. The question is whether having non 100% compliant API definition (RESTCONF-like) is show stopper, or it is a matter of having it stated in the release notes?

[italobusi]

Based on this discussion, I think that a more factual statement would be:

Implementations may use any flavor of REST APIs as long as they are based on the released TAPI R2.1 YANG models

For interoperability purposes, Implementation Agreement between concerned parties should explicitly specify which flavor of REST API has to be implemented, such as:

• Standard RESTCONF protocol (RFC8040)
• TAPI OAS (OpenAPI spec) released as part of an official TAPI release
• Any other REST API described as part of the Implementation Agreement

Any concerns with this proposal?

[openflow-lyo]

Hi Folks,

There has been quite a bit of discussion on this issue, so I am asking Karthik on behalf of the TST to pull together all the inputs from this week and put together some proposed text for the Release Notes. Hopefully we can find some text that is accurate and that everyone will agree to.

Cheers,

Lyndon

[amazzini]

This issue has been closed due to the lack of activity for more than one year. Please reopen it if follow up is necessary.