diff --git a/pep-0691.rst b/pep-0691.rst index a962c4007c9..377381a162d 100644 --- a/pep-0691.rst +++ b/pep-0691.rst @@ -51,7 +51,7 @@ did not propose any large changes to the API. In the intervening years, we've regularly talked about an "API V2" that would re-envision the entire API of PyPI. However, due to limited time constraints, -that effort has not gained much, if, any traction beyond people thinking that +that effort has not gained much, if any, traction beyond people thinking that it would be nice to do. This PEP attempts to take a different route. It doesn't fundamentally change @@ -99,7 +99,7 @@ Goals Specification ============= -To enable parsing responses with only the standard library, this PEP specifies that +To enable response parsing with only the standard library, this PEP specifies that all responses (besides the files themselves, and the HTML responses from :pep:`503`) should be serialized using `JSON `_. @@ -122,7 +122,7 @@ Similar to :pep:`629`, the major version number **MUST** be incremented if any changes to the new format would result in no longer being able to expect existing clients to meaningfully understand the format. -Likewise, incrementing the minor version **MUST** be incremented if features are +Likewise, the minor version **MUST** be incremented if features are added or removed from the format, but existing clients would be expected to continue to meaningfully understand the format. @@ -172,7 +172,7 @@ PEP: * All JSON responses will have a ``meta.api-version`` key, which will be a string that contains the :pep:`629` ``Major.Minor`` version number, with the same fail/warn - semantics as in :pep:`629`. + semantics as defined in :pep:`629`. * All requirements of :pep:`503` that are not HTML specific still apply. @@ -181,9 +181,11 @@ Project List ~~~~~~~~~~~~ The root URL ``/`` for this PEP (which represents the base URL) will be a JSON encoded -dictionary which has a single key, ``projects``, which is an array where each entry -is a dictionary with a single key, ``name``, which represents string of the project -name. As an example: +dictionary which has a two keys: +- ``projects``: An array where each entry is a dictionary with a single key, ``name``, which represents string of the project name. +- ``meta``: The general response metadata as `described earlier `__. + +As an example: .. code-block:: json @@ -355,8 +357,8 @@ Version + Format Selection -------------------------- Now that there is multiple possible serializations, we need a mechanism to allow -clients to indicate what serialization formats that they're able to understand. In -addition, it would be a benefit if any possible new major version to the API can +clients to indicate what serialization formats they're able to understand. In +addition, it would be beneficial if any possible new major version to the API can be added without disrupting existing clients expecting the previous API version. To enable this, this PEP standardizes on the use of HTTP's @@ -512,7 +514,8 @@ Servers that implement the Simple API may choose to support an URL parameter nam ``format`` to allow the clients to request a specific version of the URL. The value of the ``format`` parameter should be **one** of the valid content types. -Passing multiple content types, wild cards, quality values, etc is **not** supported. +Passing multiple content types, wild cards, quality values, etc... is **not** +supported. Supporting this parameter is optional, and clients **SHOULD NOT** rely on it for interacting with the API. This negotiation mechanism is intended to allow for easier @@ -587,7 +590,7 @@ modified to include the API version and serialization format using something lik ``simple/PROJECT/vnd.pypi.simple.v1.json``. In this case, since ``text/html`` is an alias to ``application/vnd.pypi.simple.v1+html`` -when interacting through TUF, likely it will make the most sense to normalize to the +when interacting through TUF, it likely will make the most sense to normalize to the more explicit name. Likewise the ``latest`` metaversion should not be included in the targets, only