Hi,
To help break this logjam, it would be good for us, the WG, to first agree on
the overall context of what problems we are trying to solve here. I submit they
are:
*
Provide guidance on how to evolve an extension that’s defined per STD 95.
*
Provide a way for clients and servers to negotiate extensions that are defined
per STD 95.
*
Provide a way to debug client/server implementations during draft-authoring of
an extension that’s defined per STD 95.
Please note how these problems are qualified with “STD 95” and no more. IMHO,
that’s also important for us to agree upon.
If we can at least agree on this, whether we end up with 2, 3 or more drafts is
not that relevant. At least that’s my impression. :) If the WG thinks there are
other problems we are solving here, please suggest.
James, please find below my further feedback, marked [JS2].
Thanks,
Jasdip
—
> It's much less of an issue for RDAP extension updates at the level of an RFC
> than at the level of an extension drafts if servers and clients desire to
> implement I-Ds ahead of becoming RFCs. I see the need for this to get
> implementation experience for making better extension RFCs. I don't see a
> server supporting two versions of an extension at the same time, but it is
> good that the protocol supports it if needed. One option is to support a
> default version with allowing for the client to override the default. Server
> policy will drive if there is a transition period or a hard cutover, like
> what I believe occurred with the RDAP policy update.
We incorporated Scott's idea of the "draft" prefix if there is a need to
designate an extension identifier in that way. See section 2.2.
JG-Ok that sounds good. I'm working on a detailed review of
draft-ietf-regext-rdap-extensions and from a high-level it would be helpful to
formally define the format using ABNF for the extension identifier and for the
extension elements.(e.g., query parameters, path segments, JSON members, HTTP
headers, media type parameters).
[JS] Glad to learn that the “draft” prefix idea could work for the
draft-authoring scenario. This also seems in line with insights from Mark's
blogs [1] [2]:
JG2-Do you want us to add a matching versioning type to the versioning draft
with something like “Embedded Versioning”? Adding the “draft” prefix was
somewhat of a surprise since we really didn’t get anywhere close to an
agreement on the mailing list for adding it.
Are you supportive of embedding the versioning information in the extension
identifier and changing the identifier with any change to the extension?
[JS2] Allow me to hone in on your this question.
For the former ("embedding the versioning information in the extension
identifier”), as long as it sticks to the STD 95 grammar for extensions.
Otherwise, as Pawel earlier pointed out, we would need to evolve from
“rdap_level_0”.
For the latter ("changing the identifier with any change to the extension”),
per MNOT blogs, try making changes backwards-compatible first before minting a
new extension id. So, no.
It is not considered a good idea to emulate software versioning (use of dots
with numbers) for an HTTP API like RDAP. Using a versioning query parameter in
a URI (e.g.,
"https://example.com/rdap/domain/versioning.example?versioning=point_ext1-0.1<https://secure-web.cisco.com/150GtrsSkTj2Wj8Zd2wwZbsbvV9zqlBbdEmeXn1orrfqIBPEbdIoGDQBEGXVAYvyWbabR9LJMLXjSA-4WccpUn3VPMML5_RFtwd3dq-XorLYHOTIUw40x8WUeLThv9vJe_ToflL5blubS6NURf3DTJHqAPnTZN4tng5rn5yYGFLGfNrnwf3QoExINlo3r_zZ29RBwliSRsZnnCVeKeShBMY5ylPCI_cq5fykjdpSS5SRLEE6sy5uaxm88Nc3fqXnOKdk4fefUsMJDKQowjuTJcok2ztrAEJL0i85v47ETkwQ/https%3A%2F%2Fexample.com%2Frdap%2Fdomain%2Fversioning.example%3Fversioning%3Dpoint_ext1-0.1>”)
would make identifying the resource (e.g., “versioning.example” domain)
brittle. Instead, using “draftExample0”, “draftExample1”, etc. extension id's
in the “exts_list” parameter for RDAP’s media type in Accept and/or
Content-Type headers would avoid this URI brittleness problem because such
signaling is offloaded to normal HTTP content negotiation. Per those blogs,
using opaque extension ids for major (breaking) versions of an extension should
be also fine, advising not to read too much into numbers. Yes, “draftExample0”
and “draftExample1” seem to use numbers but they might have instead been called
“hello” and “world” (per second para of section 5.4).
JG2-The point versioning is not emulating software versioning but defining the
version of the extension interface. In reviewing the blog, we came to the same
conclusion in the versioning draft, where we started by wanting to model the
versioning based on an industry known practice of semantic versioning, but that
wasn’t a good match and caused confusion. The point versioning is not
associated with software versioning but interface versioning. A client should
be capable of understanding the full interface of all the RDAP extensions
supported by the server. I don’t believe we should be mixing extension
namespace management with versioning, where you don’t want a change to a
version to become a breaking change as reflected in the blog with “sticking
software versions into Web URL removes a lot of the value we get from using
HTTP, and if you do this, you might as well be using a ‘dumb’ RPC protocol”.
In RDAP the extension prefix of an extension corresponds to the Web URL in the
blog.
[JS2] Let me try parsing above para a bit.
"The point versioning is not emulating software versioning but defining the
version of the extension interface.” … IMHO, this sentence is confusing. Is it
not reasonable to comprehend the phrase "extension interface” plainly as HTTP
API? As for the phrase “point versioning”, the word “point” in it seems to
connote some use of dots with labels when versioning, no?
"I don’t believe we should be mixing extension namespace management with
versioning, where you don’t want a change to a version to become a breaking
change as reflected in the blog with “sticking software versions into Web URL
removes a lot of the value we get from using HTTP, and if you do this, you
might as well be using a ‘dumb’ RPC protocol”.” … But, that’s exactly what
"https://example.com/rdap/domain/versioning.example?versioning=point_ext1-0.1<https://secure-web.cisco.com/150GtrsSkTj2Wj8Zd2wwZbsbvV9zqlBbdEmeXn1orrfqIBPEbdIoGDQBEGXVAYvyWbabR9LJMLXjSA-4WccpUn3VPMML5_RFtwd3dq-XorLYHOTIUw40x8WUeLThv9vJe_ToflL5blubS6NURf3DTJHqAPnTZN4tng5rn5yYGFLGfNrnwf3QoExINlo3r_zZ29RBwliSRsZnnCVeKeShBMY5ylPCI_cq5fykjdpSS5SRLEE6sy5uaxm88Nc3fqXnOKdk4fefUsMJDKQowjuTJcok2ztrAEJL0i85v47ETkwQ/https%3A%2F%2Fexample.com%2Frdap%2Fdomain%2Fversioning.example%3Fversioning%3Dpoint_ext1-0.1>”
is not heeding, no? :)
"In RDAP the extension prefix of an extension corresponds to the Web URL in the
blog.” … That’s incorrect. Extension prefix is prepended to a path segment or a
query parameter in a URI, after carefully determining if it were a breaking
versus a non-breaking change for a revision, or if it was time to mint a
superseder. That’s what section 5.4 provides guidance on.
Also see the MNOT-VERSIONING reference:
https://mnot.net/blog/2011/web_api_versioning_smackdown<https://secure-web.cisco.com/1mLCKmt3PGy4mggKFlES2qYaniu9e3bxjtlo_oZH3bo5jxCOeXNpl-lNfi65V9aNileEnrPC1Qrq1UyNh-ZOpdC2dyYum7OUuFhnypzTc72Jq3FOTnTB-d5UoZTwEYsNoaVMYINPE_6cHUoTeph7zMO-1F0v6TJBAr4vvx-QYShamBVA-nSGHQACN8sBxUN0CkoVjSk-_EiBDEJea8KB2Y5GsxYlik3HqbHIFSZPQm0mZaTXf-N3wW5oBT-ulqQngrIe8-UXT6PlZOOVICuSFM2HeBDcwOGIXNB7GvxvYpzo/https%3A%2F%2Fmnot.net%2Fblog%2F2011%2Fweb_api_versioning_smackdown>
This suggests the use of the User-Agent and Server headers when you need
software to recognize the minor revisions for the limited set of clients and
servers you may be playing with in doing development.
[JS] If software-versioning-like signaling is need during draft authoring for
minor revisions, this looks like a cheap way, no?
JG2-We can already support signaling of minor revisions in the versioning draft
via a query parameter and the RDAP media type “exts_list” parameter in
draft-ietf-regext-rdap-x-media-type if the compatibility issue is fixed in
draft-ietf-regext-rdap-x-media-type by allowing for the passing of the
extension version identifiers.
[JS2] "support signaling of minor revisions in the versioning draft via a query
parameter” … If
"https://example.com/rdap/domain/versioning.example?versioning=point_ext1-0.1<https://secure-web.cisco.com/150GtrsSkTj2Wj8Zd2wwZbsbvV9zqlBbdEmeXn1orrfqIBPEbdIoGDQBEGXVAYvyWbabR9LJMLXjSA-4WccpUn3VPMML5_RFtwd3dq-XorLYHOTIUw40x8WUeLThv9vJe_ToflL5blubS6NURf3DTJHqAPnTZN4tng5rn5yYGFLGfNrnwf3QoExINlo3r_zZ29RBwliSRsZnnCVeKeShBMY5ylPCI_cq5fykjdpSS5SRLEE6sy5uaxm88Nc3fqXnOKdk4fefUsMJDKQowjuTJcok2ztrAEJL0i85v47ETkwQ/https%3A%2F%2Fexample.com%2Frdap%2Fdomain%2Fversioning.example%3Fversioning%3Dpoint_ext1-0.1>”
exemplifies so, is that not akin to the "‘dumb' RPC protocol"? AFAICT, that
seems like a big no-no per MNOT advice.
But to be honest, I've implemented many RDAP extensions in both server and
client and have never run into any special need for explicit protocol support.
What specific issues did you have?
JG-I'm not sure how the Web API Versioning Smackdown blog matches the use case
of versioning RDAP extensions, where an RDAP extension is very broad and
doesn't typically impact the REST resource.
[JS] Beg to differ here. Being HTTP/REST/JSON-based, most, if not all, changes
for an RDAP extension affect one or more resources and/or their
representations. Furthermore, trying to make changes backwards-compatible for
an extension is encouraged before “wiping the slate clean” for an unavoidable
breaking change and creating a new extension id.
JG2-I actually found the “wiping the slate clean” in the blog as not fully
addressing the issue. From my read, it sounded like when the server removes
support for an old version that the URL would then change (e.g., move from
“/v1” to “/v2”). I don’t believe anyone is proposing the RDAP servers change
the bootstrap URL when removing support for an old extension version. We have
experience with transitioning extension versions in EPP that can be leveraged
in RDAP, where both EPP and RDAP are extensible. The OpenStack proposal in the
blog in interesting, but I don’t believe relates to RDAP extensions.
[JS2] Sorry, I need to parse this para as well.
"From my read, it sounded like when the server removes support for an old
version that the URL would then change (e.g., move from “/v1” to “/v2”).” … Not
at all. “v1” and “v2” path segments exemplify how 2 major versions could
co-exist. In RDAP's case, “exampleExt1” and “exampleExt2” would signal major
version change, and each of them would subsume any non-breaking changes (read:
minor versions). IIRC, it was raised earlier: But, how would such minor changes
be signaled? (paraphrasing). That’s where the earlier suggestion to use
Server/User-Agent headers should come handy. Please note that all this is
leveraging standard HTTP concepts and not re-inventing.
When using the point versioning in the versioning draft, the server will
support a default version of the extension as represented by the "default"
member, which can be overridden by the client using the query parameter or the
x-media exts_list parameter. This assumes that the server supports more than
one version of an extension in parallel. We could add similar support for the
opaque versioning based on adding relationships with the data members like
"predecessor" and "successor". This way the server can provide the versioning
information for the clients to understand what is supported by default and what
overrides can be provided. In the end, I view the definition of the interface
of the extensions as important for interoperability and defining the
"predecessor" and "successor" would help in a transition and help in debugging
any issues that come up at a minimum.
[JS] If “debugging” is the primary use case for numbered versioning, IMHO, it
would be prudent to consider above advice from Mark’s blog. That way, it should
be relatively cheap for both clients and servers: “draft” prefix for (breaking
and/or non-breaking) extension id's, Accept/Content-Type headers for content
negotiation, and Server/User-Agent headers for minor version signaling.
JG2-I didn’t say that “debugging” is the primary use case, but at a minimum
providing the meta-data for clients is help in debugging. We can look to add
support for the Embedding Versioning type in the versioning draft if desired
and inclusion of opaque versioning relationships in the versioning draft would
help to formally define the ordering of the opaque extensions. Can
draft-ietf-regext-rdap-x-media-type be updated to support the passing of the
Extension Version Identifier, defined in section 3.1 of
draft-ietf-regext-rdap-versioning, to enable the passing of versioning
information using the “exts”list” RDAP Media Type parameter?
[JS2] "I didn’t say that “debugging” is the primary use case, but at a minimum
providing the meta-data for clients is help in debugging.” … But please, could
you share any other practical problem the versioning draft intends solving? I
ask that to get to the heart of the matter: why would clients and servers find
it useful to go down the path of implementing the versioning draft if there is
no other use case beyond draft-authoring and if the draft-authoring use case
could be solved leveraging the standard HTTP concepts and not needing any
further invention.
That said, it'd be good to know if there are other use cases beside
draft-authoring that the versioning draft is expecting to tackle. Just asking
from what-not-to-do angle.
JG2-The versioning draft is tackling extension versioning in RDAP, with support
for extension versioning meta-data in the /help response, extension versioning
information in the RDAP query response, the ability for the client to provide a
hint of the desired extension versions using either the query parameter in
draft-ietf-regext-rdap-versioning or the “exts_list” parameter in
draft-ietf-regext-rdap-x-media-type, and finally the ability to extend the
versioning types to cover future forms of versioning. As an example, we can
formally define the Embedded Versioning type in
draft-ietf-regext-rdap-versioning if desired or the Embedded Versioning type
could be defined in a separate I-D following the template used in the
versioning draft for Opaque Versioning and Point Versioning. One option for
the versioning draft is to add a Transition Considerations section to the
template for a versioning type, which could embed some of what is defined in
the extensions draft for Opaque Versioning.
Thanks,
Jasdip
[1]
https://mnot.net/blog/2011/web_api_versioning_smackdown<https://secure-web.cisco.com/1mLCKmt3PGy4mggKFlES2qYaniu9e3bxjtlo_oZH3bo5jxCOeXNpl-lNfi65V9aNileEnrPC1Qrq1UyNh-ZOpdC2dyYum7OUuFhnypzTc72Jq3FOTnTB-d5UoZTwEYsNoaVMYINPE_6cHUoTeph7zMO-1F0v6TJBAr4vvx-QYShamBVA-nSGHQACN8sBxUN0CkoVjSk-_EiBDEJea8KB2Y5GsxYlik3HqbHIFSZPQm0mZaTXf-N3wW5oBT-ulqQngrIe8-UXT6PlZOOVICuSFM2HeBDcwOGIXNB7GvxvYpzo/https%3A%2F%2Fmnot.net%2Fblog%2F2011%2Fweb_api_versioning_smackdown>
[2]
https://mnot.net/blog/2012/api-evolution<https://secure-web.cisco.com/1C28L71CsBv3mIxbUWVjKD0wWgYhuc_QuewOK8oy7oUAbSDp4FpZlOfw2BPROe01Ug12MoPN8_6zW60lOxJX0FG55ZkB94TSRefKhhm7fRtWsCrxHxeQaNiu20hpW4eWqRTICQ0EXtnB32kdTlM7vgHoNTAUVgE3kSwE_NQzRRKBACLSWqxSCxkn7EoFc_bmskXadSf0MbU7l0uXXjBLLyvvCH_4Oh-wWoRpxEpMMLJ_y5iXFWtBlszA0gMh-mqVGQN1AxaLqIMXMNUyoI03MWLQro27_5rVA0Ui2_JndnVQ/https%3A%2F%2Fmnot.net%2Fblog%2F2012%2Fapi-evolution>
(referred from [1])
_______________________________________________
regext mailing list -- [email protected]
To unsubscribe send an email to [email protected]
