PEP 700: Additional Fields for the Simple API for Package Indexes (gh-2840)

.github/CODEOWNERS

@@ -580,6 +580,7 @@ pep-0696.rst  @jellezijlstra
 pep-0697.rst  @encukou
 pep-0698.rst  @jellezijlstra
 pep-0699.rst  @Fidget-Spinner
+pep-0700.rst  @pfmoore
 # ...
 # pep-0754.txt
 # ...

pep-0700.rst

@@ -0,0 +1,110 @@
+PEP: 700
+Title: Additional Fields for the Simple API for Package Indexes
+Author: Paul Moore <p.f.moore@gmail.com>
+PEP-Delegate: Donald Stufft <donald@stufft.io>
+Discussions-To: https://discuss.python.org/t/pep-700-additional-fields-for-the-simple-api-for-package-indexes/20177
+Status: Draft
+Type: Standards Track
+Topic: Packaging
+Content-Type: text/x-rst
+Created: 21-Oct-2022
+Post-History: `21-Oct-2022 <https://discuss.python.org/t/pep-700-additional-fields-for-the-simple-api-for-package-indexes/20177>`__
+
+
+Abstract
+========
+
+:pep:`691` defined a JSON form for the "Simple Repository API". This allowed
+clients to more easily query the data that was previously only available in
+HTML, as defined in :pep:`503`.
+
+This proposal adds three *optional* additional fields to the JSON form, which
+allow it to be used in place of PyPI's `JSON API <https://warehouse.pypa.io/api-reference/json.html>`__
+in a number of situations.
+
+- A field to allow retrieval of a list of all the published versions of a project.
+- Fields containing the size and upload time for a project file.
+
+
+Specification
+=============
+
+The proposal adds three new fields to the JSON form of the "project detail"
+pages in the simple index, located at the URL ``/<project>/``. These fields are
+*not* available in the HTML form of the page.
+
+An index MUST provide all of the specified information, for all projects and
+files, if it provides any of it. In other words, while indexes may choose to
+only support the base :pep:`691`, if they choose to support this PEP they must
+do so completely.
+
+In addition, as a technical point, this PEP reserves all field names in the JSON
+form beginning with an underscore as available for private use by indexes - no
+future PEP will assign a standardised meaning to such names.
+
+Versions
+--------
+
+An additional key, ``versions`` MAY be present at the top level, in addition to
+the keys ``name``, ``files`` and ``meta`` defined in :pep:`691`. This key, if
+present, MUST contain a list of version strings conforming to :pep:`440`, which
+list all of the project versions uploaded for this project.
+
+All of the files listed in the ``files`` key MUST be associated with one of the
+versions in the ``versions`` key, if present. The ``versions`` key MAY contain
+versions with no associated files.
+
+Additional file information
+---------------------------
+
+The elements of the ``files`` key MAY contain two additional sub-keys, ``size``
+and ``upload_time``. The ``size`` field MUST contain an integer which is the
+file size in bytes, and the ``upload_time`` field 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.
+
+FAQ
+===
+
+Why not add this data to the HTML API as well?
+----------------------------------------------
+
+It would be possible to add the data to the HTML API, but the vast majority of
+consumers for this data are likely to be currently getting it from the PyPI JSON
+API, and so will already be expecting to parse JSON. Traditional consumers of
+the HTML API have never needed this data previously.
+
+Does this imply that the HTML API is obsolete?
+----------------------------------------------
+
+No. The FAQ of :pep:`691` was clear that the HTML API is not being deprecated,
+and this PEP does not change that position. However, clients wishing to access
+the new data introduced by this PEP will need to use the JSON API to get it. And
+indexes wanting to provide it will need to serve the JSON format.
+
+Why not allow other date formats?
+---------------------------------
+
+The ISO 8601 standard is complex, and there seems little value in requiring
+clients to deal with that. The standard library ``datetime`` module provides
+methods to parse ISO 8601 strings, but it is possible that users may want to
+access index data *without* using Python (for example, piping the output of
+``curl`` into ``jq``). Having a single, well-defined format makes this easier,
+and doesn't have any significant disadvantages.
+
+What if file sizes are too big for a JSON number?
+-------------------------------------------------
+
+The JSON standard does not specify how numbers are to be interpreted. Python can
+read and write arbitrary-length integers in a JSON file, so this should not be
+an issue for code written in Python. Non-Python implementations may need to take
+care to handle large integers correctly, but this is not expected to be a
+significant problem.
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.