Remove V2 Prefix from endpoints #28
Comments
|
hmmm, that could be a rippling change. @josephschorr or @dmcgowan would just a header for docker be enough? |
|
A header won't be sufficient, unfortunately. We need some form of path prefix (whatever it may be) to ensure grouping and namespacing of the API endpoints; otherwise, they could easily conflict with other endpoints, including our own internal ones. Now, if we made the prefix configurable by responding with a header or a |
|
I'm okay with using a non-versioned prefix path! How about Examples: |
|
Speaking only for myself personally, I'd still put a version code in there, ala For example, Quay has "extensions" to the registry protocol hosted at |
|
(Oh, and if we did so, I'd vote for |
|
This is a rather tough change to make without boiling at least two oceans. I think it's important that we define things such that existing registries are compliant by assuming |
|
How about we create our own prefix, keep the @josephschorr the Quay registry only supports the |
|
@atlaskerr Quay only supports the My concern is as follows: Let's say a future change is to not change the data format, but to change the URLs themselves used (in a situation in which we do keep using REST for its, say, simplicity). In that scenario, being versioned provides a nice escape hatch without having to mix endpoints and worry about them conflicting. I do agree it is unlikely, but what is the major downside of requiring a version number as part of a prefix, when we have already agreed a prefix is useful? User confusion? |
|
Why not have no say on whether a URL prefix should exist, and rather use a |
|
@josephschorr Ah I see where you're coming from. The main reason I'd like to see a path Scenario 1: Versioned PrefixFor example, an organization wants to add image scanning functionality to their Paths at T + 1 (8 paths maintained | 3 added)
Now, lets say that V3 of the spec comes out and changes the terms Paths at T + 2 (16 paths maintained | 8 added)
After some time, the spec releases Paths at T + 3 (19 paths maintained | 3 added)
Finally, the organization feels like the spec for scanning isn't robust enough Paths at T + 4 (22 paths maintained | 3 added)
After just 1 spec upgrade and 3 proprietary feature additions/updates, the paths Scenario 2: Non-Versioned PrefixIf instead, the distribution spec standardized on a generic non-versioned Paths at T + 1 (8 paths maintained | 3 added)Add scanning:
Paths at T + 2 (13 paths maintained | 5 added)Upgrade to spec V3:
Paths at T + 3 (13 paths maintained | 0 added)Upgrade to spec V3.1:
Paths at T + 4 (13 paths maintained | 0 added)Finally, add proprietary scanning:
After the same transformations, the registry at By keeping the versioning out of the prefix, registries can add additional I think it looks nicer too! |
|
@atlaskerr Actually, I'd argue that you made my point for me with your example! :D Let's say someone did follow your example and add a custom endpoint for security scanning under Then, later, we decide to add our own security scanning endpoint to the spec... at I also don't think the perceived number of version prefixes is as large as your example provides: as mentioned, we on Quay have a I would treat the version on the path prefix like a semantic version: only change it if there is a backwards incompatible change to the URL paths defined in the specification. This would result in minimal changes (if any) to the path prefix, while still giving us the option to do so in the future if absolutely necessary. I think Docker's example here really applies: support for schema version 2 was a forward-compatible change over the existing URL paths, so no new prefix was necessary. In your example, the change to support TL;DR: Treat the version in the path prefix as a semantic version, only change when absolutely necessary. Also, to be absolutely careful, we should explicitly state to implementors to not add their custom methods under the same prefix :) |
|
@josephschorr it looks like we are at an impasse. I am in the mindset that implementers should be adding custom operations under the |
|
@atlaskerr While I disagree on the versioning aspect, I'd personally be fine with us dropping it if others disagree with my assessment on why its likely we'll need breaking changes. On the custom extensions under the same prefix, however, I'm highly concerned that we disagree: if we allow anyone to add any paths that they wish to the OCI-standard prefix, then we are in for a massive world of hurt if we ever intend to extension the API, as we have zero guarantees that semantics will be compatible at all. I don't agree that its a "fundamental part of REST" for others to be able to extend the protocol in such a manner; they certainly can do so, but they should be made aware of the risk that this can (and almost certainly will) conflict with future additions. Further, such extension seems... pointless? There is no downside, in my opinion, to custom extensions being placed into a different URL prefix; its all mostly called in an automated fashion anyway. |
|
@josephschorr What's your email? |
|
perhaps a thread on dev@opencontainers.org list
|
I understand that backwards compatibility is important but since the distribution spec's logic is based on the OCI's well defined and versioned media types, I think it should be removed.
Docker's current implementation even has a
Docker-Distribution-Api-Version: registry/2.0header which serves the same purpose and provides more meaningful information in a cleaner way.Including the path prefix and the header into the spec is kind of redundant. I'd like to see us pick one or the other before the first RC.
Thoughts?
The text was updated successfully, but these errors were encountered: