134 lines
4.3 KiB
ReStructuredText
134 lines
4.3 KiB
ReStructuredText
|
PEP: 629
|
|||
|
Title: Versioning PyPI's Simple API
|
|||
|
Author: Donald Stufft <donald@stufft.io>
|
|||
|
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::
|
|||
|
|
|||
|
<meta name="pypi:repository-version" content="1.0">
|
|||
|
|
|||
|
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:
|