request for API versioning and stable API surface

rdgordon-index commented 10 months ago

There was a very large change to https://github.com/WICG/turtledove/blob/main/FLEDGE.md -- you can see the diff compare here -- which includes a variety of changes:

the usual changes to verbiage, additional examples, security considerations, etc.
changes to expected response headers for various assets
the addition of recency to browserSignals
significant changes to address negative targeting (cf. https://github.com/WICG/turtledove/pull/780) related to https://groups.google.com/a/chromium.org/g/blink-dev/c/xzrWfs-BwFk/m/a90JCji_AAAJ

It's becoming increasingly difficult to keep track of a moving target, especially now that PAAPI is GA in Chrome.

I'd like to suggest the following:

explicit version numbering and release notes for every change to the explainer and API
clear policy for how API calls are expected to be able to determine what features are available
clear indication of which features are backwards-compatible, and which are breaking changes
no breaking changes that require either buyers or sellers to make significant changes to their implementation

For example:

How would a buyer know whether or rely on availability of recency in their bidding logic?
How would buyers and seller know when the previous request headers will no longer be acceptable by the API?
How would a seller know if they should request additional bids in the contextual auction, given that Sellers are responsible for passing additional bids to the browser at Protected Audience auction time ?

rdgordon-index commented 10 months ago

For completeness, there are other significant changes coming down the pipe:

And I have similar concerns with these changes as noted above.

rdgordon-index commented 9 months ago

https://github.com/WICG/turtledove/blob/main/Release_Notes.md doesn't seem to capture any of the changes for the last 4 months, either, so we can't rely solely on that document.

rdgordon-index commented 7 months ago

WICG / turtledove