Looks like the draft has been updated to basically describe the current API as-is.
After re-reading this thread quite a few times, I’m confused about what we’re trying to do here and why we’re doing it. I’m also feeling like we’re spending the little availability we all have, toward the wrong thing.
- Is documenting the current JSON API an absolute blocker for defining a new API? Why?
- Do we really need the current JSON API to be an interoperability standard?
- If we just wanna deprecate the current JSON API, why are we spending energy on standardising all of its
horrible behaviours quirks in detail?
- Do we want to remove the current JSON API from PyPI at some point in the future? Especially, if we have a better designed alternative + migration period?
I think we all agree that the current API has a lot of shortcomings. I think it should definitely NOT be an interoperability standard – the only reason other tooling in the ecosystem mimics our current JSON API is because there’s no alternative to that (and no one’s gonna write an XMLRPC API). Our energy is likely better spent solving the lack of a standard by building a better alternative for what we call the PyPI JSON API today.
Documenting / describing / tweaking / improving the current API is not gonna help us with the design of the new API. The new API has to be substantially different – it’s gonna have to account for a whole bunch of additional concerns that the current API doesn’t – and almost none of it is gonna be informed by the current API (not the URL structure, not most of the content schema/semantics, no
X- HTTP headers other than maybe one).
“We documented a thing so that you can continue to depend on it and implement it in other tooling” followed by “We want you move to the new alternative we created that has more constraints, because that first thing is deprecated with an EoL far away” – to me, that sounds like exactly what we should do if we wanna progress as slowly as possible – I don’t think it’s the approach we should take here. It has no compelling reasons to migrate for any of our users, we have to do additional work and we also need to keep multiple APIs alive longer.
From @nchepanov’s draft:
XXX: What is the state of
requires_dist property, is it required?
IIUC, it is populated from the upload API form’s contents:
To describe that as I understand it –
requires_dist's value are based on what the upload tool provided in the upload request, NOT by the contents of the files that have been uploaded to PyPI. Thus, if the upload tool doesn’t provide this information, this attribute is gonna be null. It is also null if the package has no dependencies.
For users, this means that you can’t rely on the dependency information in the API being correct, and the last two sentences describe a very annoying quirk that make even the available information difficult to use.