Skip to content

simple-repository-api: clean up, add API history #1808

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Feb 10, 2025
Merged

simple-repository-api: clean up, add API history #1808

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 79 additions & 72 deletions source/specifications/simple-repository-api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@
Simple repository API
=====================

The keywords "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**",
"**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**",
and "**OPTIONAL**"" in this document are to be interpreted as described in
:rfc:`2119`.

The interface for querying available package versions and
retrieving packages from an index server comes in two forms:
HTML and JSON.
Expand All @@ -28,7 +33,9 @@ Within a repository, the root URL (``/`` for this spec which represents the base
URL) **MUST** be a valid HTML5 page with a single anchor element per project in
the repository. The text of the anchor tag **MUST** be the name of
the project and the href attribute **MUST** link to the URL for that particular
project. As an example::
project. As an example:

.. code-block:: html

<!DOCTYPE html>
<html>
Expand Down Expand Up @@ -89,7 +96,9 @@ In addition to the above, the following constraints are placed on the API:
link. This exposes the :ref:`core-metadata-requires-python` metadata field
for the corresponding release. Where this is present, installer tools
**SHOULD** ignore the download when installing to a Python version that
doesn't satisfy the requirement. For example::
doesn't satisfy the requirement. For example:

.. code-block:: html

<a href="..." data-requires-python="&gt;=3">...</a>

Expand Down Expand Up @@ -209,13 +218,15 @@ Versioning PyPI's Simple API

This spec proposes the inclusion of a meta tag on the responses of every
successful request to a simple API page, which contains a name attribute
of "pypi:repository-version", and a content that is a :ref:`version specifiers
of ``pypi:repository-version``, and a content that is a :ref:`version specifiers
specification <version-specifiers>` compatible
version number, which is further constrained to ONLY be Major.Minor, and
none of the additional features supported by :ref:`the version specifiers
specification <version-specifiers>`.

This would end up looking like::
This would end up looking like:

.. code-block:: html

<meta name="pypi:repository-version" content="1.3">

Expand All @@ -241,10 +252,18 @@ is included to disambiguate with future versions (e.g. a hypothetical
simple api v2 that lived at /v2/, but which would be confusing if the
repository-version was set to a version >= 2).

This spec sets the current API version to "1.0", and expects that
future specs that further evolve the simple API will increment the
minor version number.
API Version History
-------------------

This section contains only an abbreviated history of changes,
as marked by the API version number. For a full history of changes including
changes made before API versioning, see :ref:`History <simple-repository-history>`.

- API version 1.0: Initial version of the API, declared with :pep:`629`.
- API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-time`` metadata
to the JSON serialization, declared with :pep:`700`.
- API version 1.2: Added repository "tracks" metadata, declared with :pep:`708`.
- API version 1.3: Added provenance metadata, declared with :pep:`740`.

Clients
-------
Expand Down Expand Up @@ -393,6 +412,8 @@ spec:
* All requirements of :ref:`the base HTML API specification
<simple-repository-api-base>` that are not HTML specific still apply.

* Keys (at any level) with a leading underscore are reserved as private for
index server use. No future standard will assign a meaning to any such key.

Project List
~~~~~~~~~~~~
Expand Down Expand Up @@ -446,11 +467,34 @@ The format of this URL is ``/<project>/`` where the ``<project>`` is replaced by
name for that project, so a project named "Silly_Walk" would
have a URL like ``/silly-walk/``.

This URL must respond with a JSON encoded dictionary that has three keys:
This URL must respond with a JSON encoded dictionary that has four keys:

- ``name``: The normalized name of the project.
- ``files``: A list of dictionaries, each one representing an individual file.
- ``meta``: The general response metadata as `described earlier <json-serialization_>`__.
- ``versions``: A list of version strings specifying all of the project versions
uploaded for this project. The value of ``versions`` is logically a set,
and as such may not contain duplicates, and the order of the versions is
not significant.

.. note::

All of the files listed in the ``files`` key MUST be associated with one of the
versions in the ``versions`` key. The ``versions`` key MAY contain versions with
no associated files (to represent versions with no files uploaded, if the server
has such a concept).

.. note::

Because servers may hold "legacy" data from before the adoption of
:ref:`the version specifiers specification (VSS) <version-specifiers>`, version
strings currently cannot be required to be valid VSS versions, and therefore
cannot be assumed to be orderable using the VSS rules. However, servers **SHOULD**
use normalized VSS versions where possible.

.. note::

The ``versions`` key was added with API version 1.1.

Each individual file dictionary has the following keys:

Expand Down Expand Up @@ -508,6 +552,25 @@ Each individual file dictionary has the following keys:
and is a truthy value, then it **SHOULD** be interpreted as indicating that the
file pointed to by the ``url`` field has been "Yanked" as per :ref:`the API
yank specification <simple-repository-api-yank>`.
- ``size``: A **mandatory** key. It **MUST** contain an integer which is the file size in bytes.

.. note::

The ``size`` key was added with API version 1.1.

- ``upload-time``: An **optional** key that, if present, **MUST** contain a valid
ISO 8601 date/time string in the format ``yyyy-mm-ddThh:mm:ss.ffffffZ``
which represents the time the file was uploaded to the index.

As indicated by the ``Z`` suffix, the upload time **MUST** use the UTC timezone.
The fractional seconds part of the timestamp (the ``.ffffff`` part) is optional,
and if present may contain up to 6 digits of precision. If a server does not record
upload time information for a file, it **MAY** omit the ``upload-time`` key.

.. note::

The ``upload-time`` key was added with API version 1.1.

- ``provenance``: An **optional** key which, if present **MUST** be either a JSON
string or ``null``. If not ``null``, it **MUST** be a URL to the file's
associated provenance, with the same rules as ``data-provenance`` in the
Expand All @@ -532,17 +595,20 @@ As an example:
"url": "https://example.com/files/holygrail-1.0.tar.gz",
"hashes": {"sha256": "...", "blake2b": "..."},
"requires-python": ">=3.7",
"yanked": "Had a vulnerability"
"yanked": "Had a vulnerability",
"size": 123456
},
{
"filename": "holygrail-1.0-py3-none-any.whl",
"url": "https://example.com/files/holygrail-1.0-py3-none-any.whl",
"hashes": {"sha256": "...", "blake2b": "..."},
"requires-python": ">=3.7",
"dist-info-metadata": true,
"provenance": "https://example.com/files/holygrail-1.0-py3-none-any.whl.provenance"
"provenance": "https://example.com/files/holygrail-1.0-py3-none-any.whl.provenance",
"size": 1337
}
]
],
"versions": ["1.0"]
}


Expand Down Expand Up @@ -889,71 +955,10 @@ It is recommended that clients:
- Check the ``Content-Type`` of the response and ensure it matches something
that you were expecting.

Additional Fields for the Simple API for Package Indexes
========================================================

This specification defines version 1.1 of the simple repository API. For the
HTML version of the API, there is no change from version 1.0. For the JSON
version of the API, the following changes are made:

- The ``api-version`` must specify version 1.1 or later.
- A new ``versions`` key is added at the top level.
- Two new "file information" keys, ``size`` and ``upload-time``, are added to
the ``files`` data.
- Keys (at any level) with a leading underscore are reserved as private for
index server use. No future standard will assign a meaning to any such key.

The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key is
optional.

Versions
--------

An additional key, ``versions`` MUST be present at the top level, in addition to
the keys ``name``, ``files`` and ``meta`` defined in :ref:`the JSON API
specification <simple-repository-api-json>`. This key MUST
contain a list of version strings specifying all of the project versions uploaded
for this project. The value is logically a set, and as such may not contain
duplicates, and the order of the values is not significant.

All of the files listed in the ``files`` key MUST be associated with one of the
versions in the ``versions`` key. The ``versions`` key MAY contain versions with
no associated files (to represent versions with no files uploaded, if the server
has such a concept).

Note that because servers may hold "legacy" data from before the adoption of
:ref:`the version specifiers specification (VSS) <version-specifiers>`, version
strings currently cannot be required to be valid VSS versions, and therefore
cannot be assumed to be orderable using the VSS rules. However, servers SHOULD
use normalised VSS versions where
possible.


Additional file information
---------------------------

Two new keys are added to the ``files`` key.

- ``size``: This field is mandatory. It MUST contain an integer which is the
file size in bytes.
- ``upload-time``: This field is optional. If present, it MUST contain a valid
ISO 8601 date/time string, in the format ``yyyy-mm-ddThh:mm:ss.ffffffZ``,
which represents the time the file was uploaded to the index. As indicated by
the ``Z`` suffix, the upload time MUST use the UTC timezone. The fractional
seconds part of the timestamp (the ``.ffffff`` part) is optional, and if
present may contain up to 6 digits of precision. If a server does not record
upload time information for a file, it MAY omit the ``upload-time`` key.

Rename dist-info-metadata in the Simple API
===========================================


The keywords "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**",
"**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**",
and "**OPTIONAL**"" in this document are to be interpreted as described in
:rfc:`RFC 2119 <2119>`.


Servers
-------

Expand Down Expand Up @@ -992,6 +997,8 @@ if it is present. They
**MAY** optionally use the legacy ``dist-info-metadata`` key if it is present
but ``core-metadata`` is not.

.. _simple-repository-history:

History
=======

Expand Down