Hi Jasdip,
thanks a lot for this job.
Let me share some thoughts.
Think that one of the reasons why RDAP (and modern REST APIs in general)
returns a JSON response is that JSON is schemaless so it implicitly
reduces the risk of introducing breaking changes in responses by design.
Given that an extension in RDAP might have multiple versions and, as we
have seen so far, RDAP extensions affect more responses than requests,
including version information in the response extensions seems to me a
way to treat JSON like XML and, consequently, not benefit from JSON to
be schemaless.
Following the approach A means substantially that every version update,
regardless its extent, results in a breaking change with the implicit
burden by both server and client to deprecate old versions. Please
consider what we are carrying on to potentially replace jCard with
JSContact and imagine how it would be possible to replicate it for every
single change.
Definitvely, i believe we need to define a versioning mechanism making
it easy to deal with non breaking changes that, hopefully and likely,
will be the majority.
Changes really breaking RDAP responses and requests will be treated
through a transition process from old to new versions.
I list here in the following the cases of breaking changes in REST API
that, in theory, could occur in RDAP:
* Adding a required parameter to a request
* Changing a mandatory property name
* Changing the data type of a property (no matter if it is mandatory
or optional)
* Removing a mandatory property from the response
Thus far, neither of the changes above has been argument of an RDAP
extension.
Best,
Mario
Il 20/05/2022 02:52, Jasdip Singh ha scritto:
Hi.
Honed the analysis a bit more.
Jasdip
---
**
*Approach A:*Tight coupling between extension identifier and
rdapConformance
Extension identifier = <prefix>[<version>] [ ] means optional
Registered in the IANA RDAP Extensions registry
A new spec provided for each new version of the extension
rdapConformance = <prefix>[<version>]
Extension identifier used in new data members, and in new path
segments (including any new query or matrix parameters)
*Approach B:*Lack of tight coupling between extension identifier and
rdapConformance
Extension identifier = <prefix>
Registered in the IANA RDAP Extensions registry
rdapConformance = <prefix>[<version>] [ ] means
optional
Registered in the IANA RDAP Extensions registry (or perhaps another
registry for rdapConformance)
A new spec provided for each new version of rdapConformance
Extension identifier used in new data members, and in new path
segments (including any new query or matrix parameters)
Comparing the two approaches:
Aspect
Approach A - tight coupling
Approach B - lack of tight coupling
Providing a new spec to IANA for a new version
Registry stays as-is
Registry needs to evolve for:
* Versioned rdapConformance
* Tying spec to versioned rdapConformance
Risk of breaking changes for RDAP clients
Yes, if the server now only supports the new version and a client
hasn’t evolved yet
Data member names and path segments change with each new version but
not an issue if clients have re-programmed a priori
Clients would knowingly call the versioned path segments — no guesswork
If a path segment is not affected by a new version and only a newly
versioned data sub-object is added in the response, that could break
clients
Yes, when a field is removed, or a required field is added, for a new
version
When a call is made using a non-versioned path segment, the newly
versioned rdapConformance would be checked after the fact and that
could break the client for above field additions and subtractions if
not re-programmed a priori
Clients would call non-versioned path segments but could be broken by
the new responses
Cost of reprogramming clients for the next version of an extension
There is cost but not as high as it seems — replacing version in
multiple places and accounting for field and query parameter additions
and subtractions
Longer grace period for clients to reprogram if the server supports
multiple versions during transition
There is cost — accounting for a field removal or a required field
addition
Reprogramming could become exigent for clients if the server switches
to the new version without supporting the previous version
Cost of reprogramming servers for the next version of an extension
There is a higher cost — if multiple versions are simultaneously
supported during a transition period, replicating code from the
previous version and replacing version in multiple places and
accounting for field and query parameter additions and subtractions
Eventually retiring code for the previous version
There is a lower cost — if only the latest version is supported,
accounting for a field removal or a required field addition vis-a-vis
the previous version
Server-side signaling of the next version of an extension
Add the new version of the rdapConformance in the help response and
related responses
Make URLs for new versions of path segments available
Add the new version of the rdapConformance in the help response and
related responses
No change in URLs for the new version of the rdapConformance
Potential confusion for clients
Zero since the new version is explicitly marked in data members and URLs
Not zero since the new version is not marked in data members and URLs,
and would only be discovered through the rdapConformance value in a
response
Aesthetics (does not matter to a machine but could for human friendliness)
Less
More
*From: *regext <[email protected]> on behalf of Jasdip Singh
<[email protected]>
*Date: *Thursday, May 19, 2022 at 2:15 PM
*To: *"[email protected]" <[email protected]>
*Subject: *[regext] Analysis of tight coupling between extension
identifier and rdapConformance, versus lack of
Hi.
Not sure if it is totally correct but wanted to input a strawman
analysis of the two approaches -- tight coupling between extension
identifier and rdapConformance, versus lack of -- to our discussion.
Hope this is useful.
Thanks,
Jasdip
---
*Approach A:* Tight coupling between extension identifier and
rdapConformance
Extension identifier = <prefix>[<version>] [ ] means optional
Registered in the IANA RDAP Extensions registry
A new spec provided for each new version of the extension
rdapConformance = <prefix>[<version>]
Extension identifier used in new data members, and in new path
segments (including any new query or matrix parameters)
*Approach B:* Lack of tight coupling between extension identifier and
rdapConformance
Extension identifier = <prefix>
Registered in the IANA RDAP Extensions registry
rdapConformance = <prefix>[<version>] [ ] means
optional
Registered in the IANA RDAP Extensions registry (or perhaps another
registry for rdapConformance)
A new spec provided for each new version of rdapConformance
Extension identifier used in new data members, and in new path
segments (including any new query or matrix parameters)
Comparing the two approaches:
Aspect
Approach A - tight coupling
Approach B - lack of tight coupling
Providing a new spec to IANA for a new version
Registry stays as-is
Registry needs to evolve for:
* Versioned rdapConformance
* Tying spec to versioned rdapConformance
Risk of breaking changes for RDAP clients
Yes, if the server now only supports the new version and a client
hasn’t evolved
Data member names and path segments change with each new version but
not an issue if clients have re-programmed a priori
Clients would knowingly call the versioned path segments — no guesswork
Even if a path segment is not affected by a new version but only a
newly versioned data sub-object is added in the response, that could
break clients
Yes, when a field is removed, or a required field is added, in a new
version
When a call is made using a non-versioned path segment, the newly
versioned rdapConformance would be checked after the fact and could
break the client for above field additions and subtractions if not
re-programmed a priori
Clients would call non-versioned path segments but could be broken by
the new responses
Cost of reprogramming clients for the next version of an extension
There is cost but not as high as it seems — replacing version in
multiple places and accounting for field and query parameter additions
and subtractions
There is cost but could be higher than it seems - client finds after
the fact about a field removal or a required field addition
Cost of reprogramming servers for the next version of an extension
There is cost but not as high as it seems — replacing version in
multiple places and accounting for field and query parameter additions
and subtractions
There is cost for a field removal or a required field addition
Server-side signaling of the next version of an extension
Add the new version of the rdapConformance in the help response and
related responses
Make URIs for new versions of path segments available
Add the new version of the rdapConformance in the help response and
related responses
No change in URIs for the new version of the rdapConformance
Potential confusion for clients
Zero since the new version is explicitly marked in data members and URIs
Not zero since the new version is not marked in data members and URIs
Aesthetics (should not matter to a machine but could to a human)
Less
More
_______________________________________________
regext mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/regext
--
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
