HI Pawel,
Il 03/07/2026 11:30, Pawel Kowalik ha scritto:
Hi Mario,
On 03.07.26 10:51, Mario Loffredo wrote:
Hi,
[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.".
{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.
PK2> No, old version does not have to be kept forever.
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.
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.
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.
Mario
I 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]
