Support multiple API versions

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.22.1)
+    dockerapi (1.0.0)
       base64
       excon (>= 0.97, < 2)
 

README.md

@@ -4,6 +4,7 @@ Interact with Docker API directly from Ruby code. Comprehensive implementation (
 
 * [Installation](#installation)
 * [Usage](#usage)
+  * [API version](#api-version)
   * [Images](#images)
   * [Containers](#containers)
   * [Volumes](#volumes)
@@ -52,6 +53,31 @@ If you need more information about the different Docker API endpoints, please se
 
 For a more detailed and comprehensive documentation about this gem's API, please see the [documentation page](https://rubydoc.info/gems/dockerapi).
 
+### API version
+
+The Docker API is backward-compatible, which means we can specify which version of the API we want to use. Doing so is optional in order to take advantage of a specific feature.
+
+We can specify the version to be used in 2 ways:
+
+
+Use a specific version for all new instances
+
+```ruby
+Docker::API.default_api_version="1.43"
+image = Docker::API::Image.new
+image.list.path
+=> "/v1.43/images/json"
+```
+
+Change the version used after the instance is created
+
+```ruby
+image = Docker::API::Image.new
+image.api_version="1.43"
+image.list.path
+=> "/v1.43/images/json"
+```
+
 ### Images
 
 ```ruby

Rakefile

@@ -6,5 +6,5 @@ RSpec::Core::RakeTask.new(:spec)
 task :default => :spec
 
 task :version do
-    p "v#{Docker::API::GEM_VERSION}"
+    p "v#{Docker::API::VERSION}"
 end

dockerapi.gemspec

@@ -2,7 +2,7 @@ require_relative 'lib/docker/api/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "dockerapi"
-  spec.version       = Docker::API::GEM_VERSION
+  spec.version       = Docker::API::VERSION
   spec.authors       = ["Alysson A. Costa"]
   spec.email         = ["alysson.avila.costa@gmail.com"]
 

lib/docker/api/base.rb

@@ -1,6 +1,8 @@
 ##
 # Base class to provide general methods, helpers and implementations accross classes.
 class Docker::API::Base
+    attr_accessor(:api_version)
+
     [:get, :post, :head, :delete, :put].each do | method |
         define_method(method) { | path, params = {} | self.request(method: method, path: path, params: params) }
     end
@@ -24,6 +26,7 @@ def request params
     def initialize connection = nil
         raise StandardError.new("Expected connection to be a Docker::API::Connection class") if connection != nil && !connection.is_a?(Docker::API::Connection)
         @connection = connection || Docker::API::Connection.new
+        @api_version = Docker::API.default_api_version
     end
 
     private
@@ -91,7 +94,7 @@ def hash_to_params hash
     # @param path [String]: Base URL string.
     # @param hash [Hash]: Hash object to be appended to the URL as query parameters.
     def build_path path, params = {}
-        path = "/v#{Docker::API::API_VERSION}#{path}"
+        path = "/v#{@api_version}#{path}"
         params.size > 0 ? [path, hash_to_params(params)].join("?") : path
     end
 

lib/docker/api/version.rb

@@ -1,9 +1,5 @@
 module Docker
   module API
-    GEM_VERSION = "0.22.1"
-
-    API_VERSION = "1.43"
-
-    VERSION = "Gem: #{Docker::API::GEM_VERSION} | API: #{Docker::API::API_VERSION}"
+    VERSION = "1.0.0"
   end
 end

lib/dockerapi.rb

@@ -43,6 +43,16 @@ def self.print_response_to_stdout=(bool)
       @@print_response_to_stdout = bool
     end
     self.print_response_to_stdout = false
+
+    ##
+    # This variable controls the default Docker API version.
+    def self.default_api_version
+      @@default_api_version
+    end
+    def self.default_api_version=(s)
+      @@default_api_version = s
+    end
+    self.default_api_version = "1.43"
 
   end
 end

spec/e2e/e2e_spec.rb

@@ -1,34 +1,24 @@
 RSpec.describe "End-to-end test", e2e: true do
-    before(:all) do
-
-    end
-    after(:all) do
-        Docker::API::Image.new.remove("localhost/dockerapi", force: true)
-        Docker::API::Image.new.remove("nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268", force: true)
-        File.delete("./html.tar")
-    end
-    container = Docker::API::Container.new
-    image = Docker::API::Image.new
-    volume = Docker::API::Volume.new
-    system = Docker::API::System.new
-
     describe "System calls" do 
+        system = Docker::API::System.new
         it { expect(system.ping.status).to eq(200) }
         it { expect(system.info.status).to eq(200) }
         it { expect(system.info.success?).to eq(true) }
         it { expect(system.info.json).to be_kind_of(Hash) }
-        it { expect(system.info.path).to eq("/v#{Docker::API::API_VERSION}/info") }
+        it { expect(system.info.path).to eq("/v#{Docker::API.default_api_version}/info") }
         it { expect(system.version.status).to eq(200) }
         it { expect(system.version.success?).to eq(true) }
         it { expect(system.version.json).to be_kind_of(Hash) }
-        it { expect(system.version.path).to eq("/v#{Docker::API::API_VERSION}/version") }
+        it { expect(system.version.path).to eq("/v#{Docker::API.default_api_version}/version") }
         it { expect(system.df.status).to eq(200) }
         it { expect(system.df.success?).to eq(true) }
         it { expect(system.df.json).to be_kind_of(Hash) }
-        it { expect(system.df.path).to eq("/v#{Docker::API::API_VERSION}/system/df") }
+        it { expect(system.df.path).to eq("/v#{Docker::API.default_api_version}/system/df") }
     end
 
     describe "Misc of requests that are expected to fail" do
+        container = Docker::API::Container.new
+        image = Docker::API::Image.new
         it { expect(image.create(fromImage: "doesn-exist:latest").status).to eq(404) } 
         it { expect(image.create(fromSrc: "http://404").status).to eq(500) }
         it { expect(image.details("doesn-exist").status).to eq(404) }
@@ -38,22 +28,35 @@
         it { expect(container.start("doesn-exist").status).to eq(404 )}
         it { expect(container.remove("doesn-exist").status).to eq(404) }
     end
-
-    describe "Basic workflow" do 
-        it "downloads an image" do expect(image.create( fromImage: "nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268" ).status).to be(200)  end
-        it "inspects the image" do expect(image.details( "nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268" ).json).to be_kind_of(Hash) end
-        it "tags the image" do  expect(image.tag("nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268", repo: "localhost/dockerapi").status).to be(201) end
-        it "removes an image" do expect(image.remove("nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268").status).to be(200) end
-        it "creates a volume" do expect(volume.create( Name:"dockerapi" ).status).to be(201) end
-        it "creates a container" do expect(container.create( {name: "dockerapi1"}, {Image: "localhost/dockerapi", HostConfig: {Binds: ["dockerapi:/usr/share/nginx/html"], PortBindings: {"80/tcp": [ {HostIp: "0.0.0.0", HostPort: "3080"} ]}}}).status).to be(201) end
-        it "starts container" do expect(container.start("dockerapi1").status).to be(204) end
-        it "sleeps to wait container" do sleep 2 end
-        it "requests the container on port 3080" do expect(Excon.get('http://127.0.0.1:3080').body).to match(/Welcome to nginx!/) end
-        it "copies content from container" do expect(container.get_archive("dockerapi1", "./html.tar", path: "/usr/share/nginx/html/").status).to be(200) end
-        it "verifies the content of the copied file" do expect(File.exist?("./html.tar")).to be(true) end
-        it "stops container" do expect(container.stop("dockerapi1").status).to be(204) end
-        it "waits for the container to stop" do expect(container.wait("dockerapi1").status).to be(200) end
-        it "removes container" do expect(container.remove("dockerapi1").status).to be(204) end
-        it "removes a volume" do expect(volume.remove("dockerapi").status).to be(204) end
+
+    ["1.40", "1.41", "1.42", "1.43", "1.44", "1.45", "1.46", "1.47", "1.48"].each do | version |
+        Docker::API.default_api_version = version
+        describe "Basic workflow with version #{version}" do 
+            after(:all) do
+                Docker::API::Image.new.remove("localhost/dockerapi", force: true)
+                Docker::API::Image.new.remove("nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268", force: true)
+                File.delete("./html.tar")
+            end
+            container = Docker::API::Container.new
+            image = Docker::API::Image.new
+            volume = Docker::API::Volume.new
+            it "list images using the specified API version" do expect(image.list.path).to eq("/v#{version}/images/json")  end
+            it "download an image" do expect(image.create( fromImage: "nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268" ).status).to be(200)  end
+            it "inspect the image" do expect(image.details( "nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268" ).json).to be_kind_of(Hash) end
+            it "tag the image" do  expect(image.tag("nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268", repo: "localhost/dockerapi").status).to be(201) end
+            it "remove an image" do expect(image.remove("nginx@sha256:94f1c83ea210e0568f87884517b4fe9a39c74b7677e0ad3de72700cfa3da7268").status).to be(200) end
+            it "create a volume" do expect(volume.create( Name:"dockerapi" ).status).to be(201) end
+            it "create a container" do expect(container.create( {name: "dockerapi1"}, {Image: "localhost/dockerapi", HostConfig: {Binds: ["dockerapi:/usr/share/nginx/html"], PortBindings: {"80/tcp": [ {HostIp: "0.0.0.0", HostPort: "3080"} ]}}}).status).to be(201) end
+            it "start container" do expect(container.start("dockerapi1").status).to be(204) end
+            it "sleep to wait container" do sleep 2 end
+            it "request the container on port 3080" do expect(Excon.get('http://127.0.0.1:3080').body).to match(/Welcome to nginx!/) end
+            it "copy content from container" do expect(container.get_archive("dockerapi1", "./html.tar", path: "/usr/share/nginx/html/").status).to be(200) end
+            it "verify the content of the copied file" do expect(File.exist?("./html.tar")).to be(true) end
+            it "stop container" do expect(container.stop("dockerapi1").status).to be(204) end
+            it "wait for the container to stop" do expect(container.wait("dockerapi1").status).to be(200) end
+            it "remove container" do expect(container.remove("dockerapi1").status).to be(204) end
+            it "remove a volume" do expect(volume.remove("dockerapi").status).to be(204) end
+        end
+        Docker::API.default_api_version = "1.43"
     end
 end