Hi Tom,
sorry for the delay in replying but yesterday I took a day off :-)
Please find my comments below.
Il 26/05/2022 00:33, Tom Harrison ha scritto:
Hi Mario,
On Wed, May 25, 2022 at 08:21:45PM +0200, Mario Loffredo wrote:
I'm concerned about injecting the version information into
prefixes/identifiers as I see some drawbacks in dealing with non-breaking
changes, which hopefully should be the majority and usually don't require to
manage a deprecation process.
For example, introducing a new property into a response extension would
result in returning the same information twice (e.g. the response field
"ext1_..." and response field "ext2_..." resulting from adding the new
property to "ext1_..") .
To ensure interoperability, both the response fields should coexist for a
period time so that the RDAP server could manage the sunset and then the
deprecation of "ext1_..." as smoothly as possible.
Furthermore, according to a largely used best practice in versioning REST
APIs, breaking changes should always result in a change to the major version
number while non-breaking changes, such as adding new endpoints or new
response parameters, do not require a change to the major version number.
Unfortunately, injecting the version information into the
prefixes/identifiers means that every change would break the RDAP server and
would result in a change of the major version number !?!?
If you make a backwards-compatible change, like addition of a new
field, I think one option is to update the existing specification
document by noting that there is a new 'version' of the specification
that uses the existing rdapConformance value (and prefixes, etc.) but
also includes that new field. In the case where a single field is
added, the presence or absence of that field is as good as an updated
rdapConformance value for determining which 'version' of the
specification is in use. If more complicated changes are introduced,
the specification could add its own versioning field inside a custom
element that it returns.
(To avoid any doubt, I'm not advocating for this long-term, I'm just
noting that it's possible to make backwards-compatible changes in
accordance with a 'strict' reading of the current text without
changing the names used throughout the extension.)
-Tom
Think the matter is that even the possible backwards-compatible changes
would result in being hardly backwards-compatible.
Let te me give an example to make myself clear and move the discussion
on a practical perspective.
Let's call "ext1" the rdapConformance value signaling the support of
"ext1_data" response extension. The response would be:
{
"rdapConformance" : [ ....., "ext1"],
...
"ext1_data" : { ... },
....
}
Now, let's suppose to add the field "newfield" to "ext1_data" and signal
this change by a version update from "ext1" to "ext2". The response
should be (in theory):
{
"rdapConformance" [ ....., "ext2"],
...
"ext2_data" : { ... }, // where ext2_data includes all the member of
"ext1_data" plus "newfield"
....
}
To avoid a breakage in the REST contract, the RDAP server should
implement a deprecation process ending with the replacement of
"ext1_data" with "ext2_data". This means that, for a period of time,
both the version of the response extensions should be provided:
{
"rdapConformance" [ ....., "ext1", "ext2"],
...
"ext1_data" : { ... },
"ext2_data" : { ... },
....
}
This situation would result in the following paradox as well: being the
introduction of new field in a JSON response widely considered a non
breaking change, it should be signaled by a minor version update (e.g.
"ext1_1). But, since the final effect would be the replacement of a
response field with another, a major version change should be used
instead. In short, every new version of the response extension would
imply a major version update ("ext1", "ext2", "ext3", ..) and a
consequent deprecation process the server should support.
A possible inelegant and misleading workaround would be to treat any new
version as a new extension like in the following:
{
"rdapConformance" [ ....., "ext1", "newfield1"],
...
"ext1_data" : {
...
"newfiled1" : { ... }
},
....
}
Stripping the version information from the extension prefix (Approach B
or C) would simplify the management of this case:
{
"rdapConformance": [ ....., "ext_1_1"], // (or "ext_level_1_1") to be
determined if the RDAP server should include both "ext_1" and "ext_1_1"
at least for a period of time
...
"ext_data" : {
...
"newfiled" : { ... }
},
....
}
Definitively, no breakages in the REST API contract, no deprecation
process to be managed by the server, no extra effort for both client and
server owing to the fact that JSON is schemeless and, by default, JSON
libraries don't block the deserialization of an object including an
unknown property.
A similar example is about adding a new optional query parameter to an
URI path defined by a request extension.
Guess we could face similar cases in the next future since REST services
usually evolves and, in particular, RDAP is currently still evolving.
Hence, it's fundamental to define guidelines for RDAP extensions
supporting interoperability and limiting the impact of version changes
on both client and server as much as possible.
Best,
Mario
--
Dr. Mario Loffredo
Technological Unit “Digital Innovation”
Institute of Informatics and Telematics (IIT)
National Research Council (CNR)
via G. Moruzzi 1, I-56124 PISA, Italy
Phone: +39.0503153497
Web: http://www.iit.cnr.it/mario.loffredo
_______________________________________________
regext mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/regext
