Document Our Endpoint.. Priority? SLA? Some Other Name?

[dstufft]

In practice PyPI has roughly the following "tiers" of endpoint

Tier 1 - Simple API
Tier 2 - File Upload / Web UI / JSON
Tier 3 - XMLRPC / Conveyor

This more or less ends up meaning:

Tier 1 - We do not tolerate breaking changes without a PEP, we go out of our way to avoid unplanned (or even planned) downtime.
Tier 2 - We attempt not to introduce breaking changes, but they're more likely due to a lack of standardization. We still attempt to avoid downtime, but we're more willing to accept it or to "power through it" to get through some migration. If you're able to use a Tier 1 API, you should do that, but Tier 2 is generally OK, but has an increased risk of breakages.
Tier 3 - Effectively still around because something still uses it, but should be treated as more or less unsupported, and breaking changes will be applied as needed for overall service health and/or maintainability. Nobody should use these

Maybe File Upload should be moved to Tier 1, or like a Tier 1.5, I'm not sure. I think this more or less matches the mental model that we all generally have for the various endpoints on PyPI.

If folks agree with that, we should probably document that explicitly in the API reference so that people understand how we view the various endpoints, and so they can make choices based on that.

[miketheman]

I’ve been following the draft spec over here which may prove useful for this kind of documentation. https://sla4oai.specs.governify.io/

We don’t have OpenAPI specifications for the API yet, so adding that might pave the way for this specification.

[woodruffw]

Triage: this is somewhat documented in the category splits in the user-level API docs, but not super explicitly.