PEP 629 -- Versioning PyPI's Simple API

Contents

• Abstract
• Rationale
• Overview
  • Clients
• Rejected Ideas
  • Using a Header
  • Using an URL
• Copyright

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">

When interpreting the repository version:

• Incrementing the major version is used to signal a backwards incompatible change such that existing clients would no longer be expected to be able to meaningfully use the API.
• Incrementing the minor version is used to signal a backwards compatible change such that existing clients would still be expected to be able to meaningfully use the API.

It is left up to the discretion of any future PEPs as to what specifically constitutes a backwards incompatible vs compatible change beyond the broad suggestion that existing clients will be able to "meaningfully" continue to use the API, and can include adding, modifying, or removing existing features.

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.

Rejected Ideas

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.