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 to [email protected]
