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

Streamline simple repository API specification #1442

Open
wants to merge 35 commits into
base: main
Choose a base branch
from

Conversation

EpicWink
Copy link
Contributor

@EpicWink EpicWink commented Dec 8, 2023

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

EpicWink commented Dec 8, 2023

TODO

@EpicWink
Copy link
Contributor Author

EpicWink commented Dec 8, 2023

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

EpicWink commented Dec 8, 2023

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

EpicWink commented Dec 8, 2023

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 EpicWink marked this pull request as ready for review December 8, 2023 11:47
@EpicWink
Copy link
Contributor Author

EpicWink commented Dec 8, 2023

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

Copy link
Contributor

@sinoroc sinoroc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Skimmed through. Looks good to me.

Copy link
Contributor

@jeanas jeanas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

source/specifications/simple-repository-api.openapi.yml Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
@jeanas
Copy link
Contributor

jeanas commented Dec 10, 2023

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

source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
source/specifications/simple-repository-api.rst Outdated Show resolved Hide resolved
@jeanas
Copy link
Contributor

jeanas commented Jan 25, 2024

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

@EpicWink
Copy link
Contributor Author

EpicWink commented Jan 25, 2024

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:

@webknjaz
Copy link
Member

cc @CAM-Gerlach ^

@EpicWink EpicWink changed the title Add simple repository API specification Streamline simple repository API specification May 20, 2024
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

Successfully merging this pull request may close these issues.

4 participants