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

woodruffw · woodruffw · commit caf1140041f6 · 2025-02-06T14:03:18.000-05:00
Signed-off-by: William Woodruff &lt;william@yossarian.net&gt;
diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
@@ -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.
@@ -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>
@@ -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>
 
@@ -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">
 
@@ -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
 -------
@@ -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
 ~~~~~~~~~~~~
@@ -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:
 
@@ -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
@@ -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"]
     }
 
 
@@ -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
 -------
 
@@ -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
 =======
 
