Deprecate API calls without a version #27830
Conversation
|
/cc @thaJeztah @icecrime this should be for 1.13 right ? 👼 |
| @@ -1501,7 +1501,7 @@ Search for an image on [Docker Hub](https://hub.docker.com). | |||
|
|
|||
| **Example request**: | |||
|
|
|||
| GET /images/search?term=sshd HTTP/1.1 | |||
| GET /v1.18/images/search?term=sshd HTTP/1.1 | |||
There was a problem hiding this comment.
hmf, this is gonna be a nightmare to keep the API docs in sync. Well, until we move to Swagger 😄
There was a problem hiding this comment.
Even with static docs, it isn't too bad – you just have to do a big regex search/replace for each new version.
I did something like this: s/(GET|POST|PATCH|PUT|HEAD|OPTIONS) \/(.+?) HTTP/$1 /v1.25/$2 HTTP/
But yeah... hopefully Swagger will do this for v1.26. ;)
There was a problem hiding this comment.
We should add that to the release-checklist (there's a section in there that explains bumping the API version)
|
It's ok to discuss for 1.13, but no decision was made yet I think. Should we have a redirect? (does that even work if a socket connection is used?) |
|
We could have a redirect when it is deprecated, but I don't think we should do it now. It will break clients which do not follow redirects. E.g. even curl doesn't do it by default. |
|
@vieux Perhaps |
|
@bfirsh can you add this to https://github.com/docker/docker/blob/master/docs/deprecated.md as well? |
|
Idea sounds good to me. We're saying that the version is required, to prepare people and get them ready for the actual change made in a couple of versions, per the deprecation policy. There's no code change, just documentation, because we already support versioned access on the API. Thus we only need doc changes for now. As above, we should mention it in the deprecation section. I am kind of surprised we didn't have the version hardcoded on each of the version specific pages. |
See moby#21157 for more details. In a future version of Docker, providing a version to API calls will be mandatory. An implementation of this is in moby#27801. Signed-off-by: Ben Firshman <ben@firshman.co.uk>
bfirsh
force-pushed
the
deprecate-no-version-in-api-urls
branch
from
7d5127b to
6b9e375
Compare
|
@thaJeztah Done! ✨ @vieux Do you think making |
|
I'm ok with only |
|
needs a rebase, so carried in #28208 |
- What I did
At some point it would be good to make providing a version to API calls mandatory. See #21157 for more information.
However, this will break clients, so we should mark it as deprecated before making the change. See #27801 for the proposed actual change and discussion around deprecation.
- Description for the changelog
Not providing an API version in API calls is now deprecated, and those endpoints will be removed in a future version of Docker. Instead of just requesting, for example, the URL /containers/json, you must now request /v1.25/containers/json.