{"action":"created","issue":{"url":"https://api.github.com/repos/docker/docker/issues/21927","repository_url":"https://api.github.com/repos/docker/docker","labels_url":"https://api.github.com/repos/docker/docker/issues/21927/labels{/name}","comments_url":"https://api.github.com/repos/docker/docker/issues/21927/comments","events_url":"https://api.github.com/repos/docker/docker/issues/21927/events","html_url":"https://github.com/docker/docker/issues/21927","id":147406897,"number":21927,"title":"Proposal: Add a versioning scheme to the plugin API","user":{"login":"holgerreif","id":12717933,"avatar_url":"https://avatars.githubusercontent.com/u/12717933?v=3","gravatar_id":"","url":"https://api.github.com/users/holgerreif","html_url":"https://github.com/holgerreif","followers_url":"https://api.github.com/users/holgerreif/followers","following_url":"https://api.github.com/users/holgerreif/following{/other_user}","gists_url":"https://api.github.com/users/holgerreif/gists{/gist_id}","starred_url":"https://api.github.com/users/holgerreif/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/holgerreif/subscriptions","organizations_url":"https://api.github.com/users/holgerreif/orgs","repos_url":"https://api.github.com/users/holgerreif/repos","events_url":"https://api.github.com/users/holgerreif/events{/privacy}","received_events_url":"https://api.github.com/users/holgerreif/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/docker/docker/labels/area/api","name":"area/api","color":"e11d21"},{"url":"https://api.github.com/repos/docker/docker/labels/kind/enhancement","name":"kind/enhancement","color":"E8CAAF"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2016-04-11T12:05:04Z","updated_at":"2016-04-11T13:35:51Z","closed_at":null,"body":"### Problem Statement\r\nFor the docker Remote API there is a sound versioning scheme in place even with [history](https://docs.docker.com/engine/reference/api/docker_remote_api/#version-history).\r\n\r\nFor the plugin API only a [single mention](https://docs.docker.com/engine/extend/plugin_api/#api-design) of versioning can be found:\r\n\r\n_The API is versioned via an Accept header, which currently is always set to `application/vnd.docker.plugins.v1+json`._\r\n\r\nAccording to [this comment](https://github.com/docker/docker/issues/21857#issuecomment-207057067) there are possible changes in how the API works and/or is used. Furthermore, in contrast to the Remote API which is only implemented once (by docker engine, and of course swarm) the plugin API is implemented by a variety of services provided by different vendors.  \r\n\r\nTherefore I see the need to introduce versioning information for this API.\r\n\r\n### Requirements\r\n   1. API Client (docker daemon) should indicate which version of the API it is supporting.\r\n   2. API Service (plugin) should inidicate which version of the API it is supporting.\r\n   3. For every API call it should be clear, which API version it refers to.\r\n   4. A history for the versions should be maintained.\r\n\r\n### Possible implementation\r\nWhen the Plugin gets activated, the payload (currently empty) specifies, which plugin types for which API version is supported.\r\n**Request**\r\n```\r\n{\r\n    [ \r\n        { \r\n            \"PluginType\" : string, \r\n            \"APIVersion\" : string\r\n        }\r\n   ]\r\n}\r\n```\r\nThe following `PluginType`s are currently defined:  `authz` - `NetworkDriver` - `VolumeDriver`.\r\nIf for a given `PluginType` more then one APIVersion is supported it is listed multiple times. \r\n\r\n**Response**\r\nThe response indicates which Docker subsystems the plugin implements.\r\n```\r\n{\r\n    \"Implements\": [ \r\n    {\r\n        \"PluginType\" : string, \r\n        \"APIVersion\" : string\r\n    }\r\n    ]\r\n}\r\n```\r\nAt its own discretion the plugin can return only those `APIVersion` that the daemon also supports or it can return all versions.\r\nDocker Daemon can pick any of the supported `APIVersion` to communicate with the plugin. The daemon should stick with the version selected at the beginning of communication, changing API version during lifetime of plugin may result in undefined behaviour.\r\nIf the plugin supports more then one Docker subsystem,  the plugin may support different API versions for different subsystems. The order of entries in the list indicates plugin's preferences.\r\nSimilarily Docker daemon may use different API version when talking to different subsystems the plugin implements.\r\n\r\n**API-Calls**\r\nThe Version of the API-Call is encoded similiar the Remote API. A call gets the API version prepended, e.g. `/v1/VolumeDriver.List`. A call without the version prefix menas the version of the first list entry for this subsystem returned by the plugin as responss to plugin activation. \r\n_This is not necessary the highest version currently specified or the highest version supported by daemon!_.\r\n\r\n**History**\r\nChanges between different versions should be tracked either in the [plugin documentation overview](https://docs.docker.com/engine/extend/plugin_api/) or in the documentation of the various subsystems ([volume](https://docs.docker.com/engine/extend/plugins_volume/), [network](https://docs.docker.com/engine/extend/plugins_network/)).\r\n\r\nSince the API comprises alls subsystems the API version is comprises all subsystems to.. Thus it is possible, that for a given subsystem no change exists between subsequent version.\r\n\r\n### Notes\r\nWhile this proposal could be part of #20363 too, I feel the discussion there is to wide and partly orthogonal. Thus I present this as a separate issue."},"comment":{"url":"https://api.github.com/repos/docker/docker/issues/comments/208346467","html_url":"https://github.com/docker/docker/issues/21927#issuecomment-208346467","issue_url":"https://api.github.com/repos/docker/docker/issues/21927","id":208346467,"user":{"login":"holgerreif","id":12717933,"avatar_url":"https://avatars.githubusercontent.com/u/12717933?v=3","gravatar_id":"","url":"https://api.github.com/users/holgerreif","html_url":"https://github.com/holgerreif","followers_url":"https://api.github.com/users/holgerreif/followers","following_url":"https://api.github.com/users/holgerreif/following{/other_user}","gists_url":"https://api.github.com/users/holgerreif/gists{/gist_id}","starred_url":"https://api.github.com/users/holgerreif/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/holgerreif/subscriptions","organizations_url":"https://api.github.com/users/holgerreif/orgs","repos_url":"https://api.github.com/users/holgerreif/repos","events_url":"https://api.github.com/users/holgerreif/events{/privacy}","received_events_url":"https://api.github.com/users/holgerreif/received_events","type":"User","site_admin":false},"created_at":"2016-04-11T13:35:50Z","updated_at":"2016-04-11T13:35:50Z","body":"> A call without the version prefix means the version of the first list entry for this subsystem returned by the plugin as responss to plugin activation. \r\n\r\nThis should be aligned with #21157 (Proposal: make version mandatory in API URLs)"}}