Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

request for API versioning and stable API surface #823

Open
rdgordon-index opened this issue Sep 24, 2023 · 3 comments
Open

request for API versioning and stable API surface #823

rdgordon-index opened this issue Sep 24, 2023 · 3 comments

Comments

@rdgordon-index
Copy link
Contributor

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:

  1. the usual changes to verbiage, additional examples, security considerations, etc.
  2. changes to expected response headers for various assets
  3. the addition of recency to browserSignals
  4. significant changes to address negative targeting (cf. Add Additional Bids and Negative Targeting to the Explainer. #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
Copy link
Contributor Author

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

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

@rdgordon-index
Copy link
Contributor Author

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
Copy link
Contributor Author

As per the WICG meeting, https://github.com/WICG/turtledove/blob/main/PA_Feature_Detecting.md was recently published by @JensenPaul

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant