From 797236340738c92adcae89bd6942d4887e5bdd1b Mon Sep 17 00:00:00 2001 From: Donald Stufft Date: Thu, 16 Jul 2020 12:50:19 -0400 Subject: [PATCH] PEP 629: Add versioning to PyPI's Simple API (GH-1528) --- pep-0629.rst | 133 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 pep-0629.rst diff --git a/pep-0629.rst b/pep-0629.rst new file mode 100644 index 000000000..61f547f91 --- /dev/null +++ b/pep-0629.rst @@ -0,0 +1,133 @@ +PEP: 629 +Title: Versioning PyPI's Simple API +Author: Donald Stufft +Discussions-To: https://discuss.python.org/ +Status: Draft +Type: Standards Track +Content-Type: text/x-rst +Created: 16-Jul-2020 +Post-History: 16-Jul-2020 + + +Abstract +======== + +This PEP proposes adding a method for versioning the simple API so +that clients can determine which features of the simple API that a +specific repository supports. + + +Rationale +========= + +When evolving the simple API, clients wish to be able to determine +which features the repository supports. Currently there is no +mechanism to do this, except by attempting to detect new features +by looking at the data in the reponses and see if it appears like +a particular feature is in use. + +This works reasonably well for a modern version of a client to determine +if the repository supports all of the features it wants to implement, +however it does not do anything to tell an older version the client that +the repository supports features that it might not understand and to +allow messaging to indicate that it might not be correctly understanding +the output of the repository. + +An example of a scenario where this happened was the phasing in of +python-requires metadata, while existing clients could still successfully +use the repository, they were lacking the ability to understand this new +piece of data which would have informed their behavior to select a better +file for end users. + + +Overview +======== + +This PEP proposes the inclusion of a meta tag on the responses of every +sucessful request to a simple API page, which contains a name attribute +of "pypi:repository-version", and a content that is a PEP 440 compatible +version number, which is further constrained to ONLY be Major.Minor, and +none of the additional features supported by PEP 440. + +This would end up looking like:: + + + +Interpretation of this version is that incrementing the major version +is considereed a backwards incompatible change such that existing +clients would no longer be expected to be able to meaningfully use the +new API, and incrementing the minor version is a backwards compatible +change that existing clients would no longer be able to meaningfully +use the API. + +It is expectation of this PEP that the major version will never be +incremented, and any future major API evolutions would utilize a +different mechanism for API evolution. However the major version +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 PEP sets the current API version to "1.0", and expects that +future PEPs that further evolve the simple API will increment the +minor version number. + + +Clients +------- + +Clients interacting with the simple API **SHOULD** introspect each +response for the repository version, and if that data does not exist +**MUST** assumee that it is version 1.0. + +When encountering a major version greater than expected, clients +**MUST** hard fail with an appropiate error message for the user. + +When encountering a minor version greater than expected, clients +**SHOULD** warn users with an appropiate message. + +Clients **MAY** still continue to use feature detection in order to +determine what features a repository uses. + + +Rejected Ideas +============== + +Using a Header +-------------- + +Instead of baking this information into the actual HTML, an +alternative would be to use a HTTP header. This idea was +considered and ultimately was rejected because it would make +mirrors have to start modifying headers instead of being able +to operate as a "dumb" HTTP server of files. + + +Using an URL +------------ + +Another traditional mechanism for versioning APIs is to bake it +into the URL, something like ``/1.0/simplee/`` or so. This works +well for major version changes where olders clients are not +expected to be capable of continuing to use it, but it is not +well suited to minor version bumps, particularly when the version +numbers can be viewed as largely advisory for end users. + + + + +Copyright +========= + +This document is placed in the public domain or under the +CC0-1.0-Universal license, whichever is more permissive. + + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: