PEP 694 -- PyPI upload API 2.0 (Round 2)

[woodruffw (William Woodruff)]

Sorry for the delayed bump!

I did another read through of PEP 694, and I think it’s great. One thing I wanted to call out: the current draft defines its own error response schema:

Clients in general should be prepared to handle HTTP response error status codes which MAY contain payloads of the the following format:

{ “meta”: { “api-version”: “2.0” }, “message”: “…”, “errors”: [ { “source”: “…”, “message”: “…” } ] }

Instead of a custom schema here, do you have opinions on aligning this with an RFC, e.g. RFC 9457? I recently made a similar change to PEP 807 to use the standard “problem details” format, with the idea being that it’s uniform and HTTP clients can often handle it gracefully out of the box. I was also hoping to (soon) propose a change to the standard index APIs, to encourage error responses to use these “problem detail” formats too:

Does it make sense to standardize index error responses?

This is something I’ve been thinking about recently, since it came up with how PEP 807 plans to encode its error responses. TL;DR: the current simple index standards (PEP 503 / PEP 691 and their living forms) adequately describe the shape of successful index responses, but not the shape of failure responses. As a result, installer clients (pip, uv, poetry, etc.) frequently have to assume a lowest common denominator of HTTP error code semantics, which in turn are frequently sparse or inaccurate …

(The nice thing about that RFC is that it’s pretty flexible – as long as the overall shape conforms to a “problem detail,” we can include custom keys like meta to convey the api-version, etc.!)