Hi Mario,all of that is true, but it describes only a situation when "versioning" draft is in place for an extension.
"extensions" draft shall however describe also a situation when "versioning" is not in place, which applies to all current existing extensions.
The question in the end is, related to future extensions:- if an extension has a normative requirement for both client and server to implement "versioning" draft as pre-requisite (or generally speaking any other way of signalling version evolution, including some own built-in mechanics), shall it be allowed to make otherwise breaking changes without change of extension identifier, or not? A side note - a normative reference to "versioning" draft is not sufficient imho, it shall be obligation to implement.
Pro: more flexibility in extension evolution with lower granularity, lower maintenance of clients and servers Con: more complex processing by the clients, as they would have to check not only the conformance array but also the versioning array.
I think I can go with accepting it to move forward. Kind regards, Pawel On 03.07.26 13:15, Mario Loffredo wrote:
HI Pawel, Il 03/07/2026 11:30, Pawel Kowalik ha scritto:Hi Mario, On 03.07.26 10:51, Mario Loffredo wrote:Hi,{ML] Unless you are saying that old versions must be kept forever, at a certain time a server decides that it's time to remove the old version because it evaluates low to zero the probability of breaking a client.[snip PK]I just wanted to point out, that fulfilment of this condition can never be stated with certainty by the server "clients have switched from the old version to the new one.".PK2> No, old version does not have to be kept forever.PK2> for me not at all. As Client implementer it is very different to see that (a deprecated) API version (extension identifier) is gone, where there is clear signalling about it (RDAP conformance) as opposed to seeing a response which is missing some fields or having the fields with changed syntax and semantics. The code paths that don't break in terms of exception are here even more dangerous that the ones that face an exception.Basically client has no way to tell the server if it switched or not, because it happens only after the response has been received from the server.Also in most cases not every client is even known to the server, when out-of-band approaches would come into consideration. Only in case of restricted access RDAP with authentication of clients this may be considered at all.In terms of interoperability it is something different if the client would notice the extension it used to process is not there any longer as opposed to receiving a response with a known extension identifier but with the content which cannot be processed.[ML] Unless a client implements some sort of defensive parsing, the result seems identical to me.From the perspective of the effort required for both clients and servers to align their implementation to the new version, the two strategies are not at all comparable.Forcibly maximizing the scope of any breaking change seems messy to me and the opposite of what REST API developers are used to.PK2> The list as it is now formulated in the draft is exactly based on what REST API developers are used to. See GitHub API Policy [1] as an example. Especially this part: "Breaking changes are changes that can potentially break an integration. Breaking changes will be released in a new API version."Extension identifier is for me an equivalent of "new API version" for an extension.[1] https://docs.github.com/en/rest/about-the-rest-api/breaking-changes[ML2] It seems to me that GitHub's strategy is closer to what I'm saying (and what is explained in the versioning draft) than to what you stated.For each reported breaking change, the scope of the change is limited to a specific endpoint (i.e., "Affected Endpoints"). The rest of GitHub's APIs are unaffected.Changing the extension identifier would instead be equivalent to renaming the prefix of all endpoints, e.g., /v1, /v2.Instead, GitHub has chosen to use a server-side compatibility approach like the one I discussed to minimize the scope of each change and limit it to just the affected endpoint.This is evident from the first breaking change listed in version 2026-03-10 (https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2026-03-10#version-2022-11-28):*Remove deprecated |rate| property from rate limit endpoint* The |rate| property has been deprecated since 2021 and duplicates information available in the |resources.core| property. To migrate, update your integration to read rate limit information from |resources.core| instead of |rate|.See https://docs.github.com/rest/rate-limit for updated documentation. *Affected endpoints* * |GET /rate_limit| This is the response of the version before 2026-03-10. { "*resources*": { "*core*": { "limit": 5000, "used": 1, "remaining": 4999, "reset": 1691591363 }, "search": { "limit": 30, "used": 12, "remaining": 18, "reset": 1691591091 }, "graphql": { "limit": 5000, "used": 7, "remaining": 4993, "reset": 1691593228 }, "integration_manifest": { "limit": 5000, "used": 1, "remaining": 4999, "reset": 1691594631 }, "source_import": { "limit": 100, "used": 1, "remaining": 99, "reset": 1691591091 }, "actions_runner_registration": { "limit": 10000, "used": 0, "remaining": 10000, "reset": 1691594631 }, "scim": { "limit": 15000, "used": 0, "remaining": 15000, "reset": 1691594631 }, "dependency_snapshots": { "limit": 100, "used": 0, "remaining": 100, "reset": 1691591091 }, "code_search": { "limit": 10, "used": 0, "remaining": 10, "reset": 1691591091 }, "code_scanning_autofix": { "limit": 10, "used": 0, "remaining": 10, "reset": 1691591091 } }, "*rate*": { "limit": 5000, "used": 1, "remaining": 4999, "reset": 1372700873 } }Using the X-GitHub-Api-Version parameter is equivalent to using the versioning parameter for clients and the versioning_help response member for servers. However, the response is different when the client requests a version that is no longer supported (https://docs.github.com/en/rest/about-the-rest-api/api-versions?apiVersion=2026-03-10#specifying-an-api-version).If you specify an API version that is no longer supported, you will receive a 410 Gone response.Additionally, version sunsetting and deprecation are announced via the relevant HTTP headers of RFC 7231 and RFC 8594 (https://docs.github.com/en/rest/about-the-rest-api/api-versions?apiVersion=2026-03-10#api-version-closing-down), which are equivalent to the information provided by the versioning_help response member.MarioI could be wrong, but I believe the direct consequence will be that extension providers will write specifications that define as many sub-extensions as there are core components of the extension (e.g., JSON names, URLs, etc.).PK2> ... I may be wrong as well by thinking that the other consequence would be for extension providers to be very careful about back-compatibility, which in such open and multi-party system like RDAP is a wished outcome. The approach you outline may be a way some people find useful - we'll see.Conversely, if we want to allow extension providers to choose the scope of a change in their extension (including the option to turn a breaking change into a non-breaking change + a deprecation process of specific extension components), we should ensure that the `exts_list` parameter includes the extension versions as defined in the versioning draft.PK2> Here I agree, but this is likely a different conversation.This would provide servers with more information about when it's appropriate to remove the old version.PK2> which can be indeed useful Kind Regards, Pawel _______________________________________________ regext mailing list [email protected] To unsubscribe send an email [email protected]-- Dott. Mario Loffredo Senior Technologist Technological Unit “Digital Innovation” Institute of Informatics and Telematics (IIT) National Research Council (CNR) Address: Via G. Moruzzi 1, I-56124 PISA, Italy Phone: +39.0503153497 Web:http://www.iit.cnr.it/mario.loffredo _______________________________________________ regext mailing list [email protected] To unsubscribe send an email [email protected]
smime.p7s
Description: S/MIME Cryptographic Signature
_______________________________________________ regext mailing list -- [email protected] To unsubscribe send an email to [email protected]
