Streamline simple repository API specification

[EpicWink]

• More fleshed-out introduction to the API
• Define specification for latest standard of both HTML and JSON formats
  • For each API endpoint, its features are described generally, then how those features are provided are described for each format
  • The specifications are summarised (without loss of precision) from the PEPs (and former specification sections) to ease reading. Let me know if more/all of the specifications should be added to the PEP. I've left out some clarifying notes, rationale, recommendations, etc
  • The specs were added as prose, but perhaps something akin to API docs is more suitable
• Add OpenAPI spec, specifically detailing the JSON format (inside collapsible)
• Convert existing history to bullet-list

Solves part of #1093

---

📚 Documentation preview 📚: https://python-packaging-user-guide--1442.org.readthedocs.build/en/1442/

[EpicWink]

TODO

• Add base HTML format specification
• Add yank support
• Add versioning metadata
• Add package metadata file
  • Renamed
• Add base JSON format specification
• Add client format selection
• Add additional fields to JSON format
• Ascertain API is HTTP-based
• PEP 708 - see Add PEP 708 to simple repository API EpicWink/packaging.python.org#3

[EpicWink]

PEP 503 says nothing about the API being provided via HTTP, while PEP 691 clearly assumes it (I don't think it goes so far as to say that the index server must be using HTTP, though: just use HTTP features like content-negotiation)

[EpicWink]

PEP 503 is unclear as to whether the project-details lists GPG signature files (ie do they get an <a> element as well?), or if they're only implied. Same goes for core-metadata files.

I'll work under the assumption that they're only implied.

[EpicWink]

I don't understand how any of these specs relate to PEP 458 (Secure PyPI downloads with signed repository metadata), so I'll leave that out completely for now.

[EpicWink]

I think this MR could be squash-merged: no need to keep the commit history I think

[sinoroc]

Skimmed through. Looks good to me.

[jeanas]

This looks great! Here are some nitpicks, bearing in mind that I don't have the details of this API in mind so I haven't checked that the text conforms to the PEPs.

[jeanas]

@dstufft You might be interested in reviewing this, maybe also @pfmoore?

[jeanas]

@EpicWink What is the status of this PR now that #1477 has been merged?

[EpicWink]

What is the status of this PR now that #1477 has been merged?

@jeanas this change is a more focused write-up of the simple repo API spec, rather than a copy of the PEPs. This PR is still open for consideration, however some questions I asked above are not answered yet:

• Is the API based on HTTP?
• Are GPG signature and core-metadata files to be listed in the project files page?
• How does PEP 458 relate to the simple repo API spec?
• Have I summarised the specs too much?
• Should the specs be displayed as API docs instead of prose (I think I started on this with the JSON format portion)?

[webknjaz]

cc @CAM-Gerlach ^