diff --git a/config.ld b/config.ld
index 084fa3f7971d..a4264657fe90 100644
--- a/config.ld
+++ b/config.ld
@@ -11,5 +11,5 @@ dir='doc'
 --readme='readme.md'
 sort=true
 sort_modules=true
-not_luadoc=true
+--not_luadoc=true
 all=false
diff --git a/kong-0.9.7-0.rockspec b/kong-0.9.7-0.rockspec
index 0f19736154f9..440fafe277e0 100644
--- a/kong-0.9.7-0.rockspec
+++ b/kong-0.9.7-0.rockspec
@@ -75,6 +75,7 @@ build = {
     ["kong.api.routes.plugins"] = "kong/api/routes/plugins.lua",
     ["kong.api.routes.cache"] = "kong/api/routes/cache.lua",
     ["kong.api.routes.cluster"] = "kong/api/routes/cluster.lua",
+    ["kong.api.routes.upstreams"] = "kong/api/routes/upstreams.lua",
 
     ["kong.tools.dns"] = "kong/tools/dns.lua",
     ["kong.tools.utils"] = "kong/tools/utils.lua",
@@ -101,6 +102,8 @@ build = {
     ["kong.dao.schemas.nodes"] = "kong/dao/schemas/nodes.lua",
     ["kong.dao.schemas.consumers"] = "kong/dao/schemas/consumers.lua",
     ["kong.dao.schemas.plugins"] = "kong/dao/schemas/plugins.lua",
+    ["kong.dao.schemas.upstreams"] = "kong/dao/schemas/upstreams.lua",
+    ["kong.dao.schemas.targets"] = "kong/dao/schemas/targets.lua",
     ["kong.dao.db"] = "kong/dao/db/init.lua",
     ["kong.dao.db.cassandra"] = "kong/dao/db/cassandra.lua",
     ["kong.dao.db.postgres"] = "kong/dao/db/postgres.lua",
diff --git a/kong/api/crud_helpers.lua b/kong/api/crud_helpers.lua
index efa67bd5643e..ca014045f265 100644
--- a/kong/api/crud_helpers.lua
+++ b/kong/api/crud_helpers.lua
@@ -41,6 +41,24 @@ function _M.find_consumer_by_username_or_id(self, dao_factory, helpers)
   end
 end
 
+function _M.find_upstream_by_name_or_id(self, dao_factory, helpers)
+  local filter_keys = {
+    [utils.is_valid_uuid(self.params.name_or_id) and "id" or "name"] = self.params.name_or_id
+  }
+  self.params.name_or_id = nil
+
+  local rows, err = dao_factory.upstreams:find_all(filter_keys)
+  if err then
+    return helpers.yield_error(err)
+  end
+
+  -- We know name and id are unique, so if we have a row, it must be the only one
+  self.upstream = rows[1]
+  if not self.upstream then
+    return helpers.responses.send_HTTP_NOT_FOUND()
+  end
+end
+
 function _M.paginated_set(self, dao_collection)
   local size = self.params.size and tonumber(self.params.size) or 100
   local offset = self.params.offset and ngx.decode_base64(self.params.offset) or nil
diff --git a/kong/api/init.lua b/kong/api/init.lua
index 17bb1873c886..112c97e80c4f 100644
--- a/kong/api/init.lua
+++ b/kong/api/init.lua
@@ -110,7 +110,7 @@ end
 ngx.log(ngx.DEBUG, "Loading Admin API endpoints")
 
 -- Load core routes
-for _, v in ipairs({"kong", "apis", "consumers", "plugins", "cache", "cluster" }) do
+for _, v in ipairs({"kong", "apis", "consumers", "plugins", "cache", "cluster", "upstreams" }) do
   local routes = require("kong.api.routes."..v)
   attach_routes(insert_405(routes))
 end
diff --git a/kong/api/routes/upstreams.lua b/kong/api/routes/upstreams.lua
new file mode 100644
index 000000000000..5b97bb612b97
--- /dev/null
+++ b/kong/api/routes/upstreams.lua
@@ -0,0 +1,110 @@
+local crud = require "kong.api.crud_helpers"
+
+return {
+  ["/upstreams/"] = {
+    GET = function(self, dao_factory)
+      crud.paginated_set(self, dao_factory.upstreams)
+    end,
+
+    PUT = function(self, dao_factory)
+      crud.put(self.params, dao_factory.upstreams)
+    end,
+
+    POST = function(self, dao_factory, helpers)
+      crud.post(self.params, dao_factory.upstreams)
+    end
+  },
+
+  ["/upstreams/:name_or_id"] = {
+    before = function(self, dao_factory, helpers)
+      crud.find_upstream_by_name_or_id(self, dao_factory, helpers)
+    end,
+
+    GET = function(self, dao_factory, helpers)
+      return helpers.responses.send_HTTP_OK(self.upstream)
+    end,
+
+    PATCH = function(self, dao_factory)
+      crud.patch(self.params, dao_factory.upstreams, self.upstream)
+    end,
+
+    DELETE = function(self, dao_factory)
+      crud.delete(self.upstream, dao_factory.upstreams)
+    end
+  },
+
+  ["/upstreams/:name_or_id/targets/"] = {
+    before = function(self, dao_factory, helpers)
+      crud.find_upstream_by_name_or_id(self, dao_factory, helpers)
+      self.params.upstream_id = self.upstream.id
+    end,
+
+    GET = function(self, dao_factory)
+      crud.paginated_set(self, dao_factory.targets)
+    end,
+
+    POST = function(self, dao_factory, helpers)
+      -- when to cleanup: invalid-entries > (valid-ones * cleanup_factor)
+      local cleanup_factor = 10
+      
+      --cleaning up history, check if it's necessary...
+      local target_history = dao_factory.targets:find_all(
+            { upstream_id = self.params.upstream_id })
+
+      if target_history then --ignoring errors here, will be caught when posting below
+        -- sort the targets
+        for _,target in ipairs(target_history) do
+          target.order = target.created_at..":"..target.id
+        end
+
+        -- sort table in reverse order
+        table.sort(target_history, function(a,b) return a.order>b.order end)
+        -- do clean up
+        local cleaned = {} 
+        local delete = {}
+
+        for _, entry in ipairs(target_history) do
+          if cleaned[entry.target] then
+            -- we got a newer entry for this target than this, so this one can go
+            delete[#delete+1] = entry
+
+          else
+            -- haven't got this one, so this is the last one for this target
+            cleaned[entry.target] = true
+            cleaned[#cleaned+1] = entry
+            if entry.weight == 0 then
+              delete[#delete+1] = entry
+            end
+          end
+        end
+        
+        -- do we need to cleanup?
+        -- either nothing left, or when 10x more outdated than active entries
+        if (#cleaned == 0 and #delete > 0) or
+           (#delete >= (math.max(#cleaned,1)*cleanup_factor)) then
+
+          ngx.log(ngx.INFO, "[admin api] Starting cleanup of target table for upstream ", 
+                            tostring(self.params.upstream_id))
+          local cnt = 0
+          for _, entry in ipairs(delete) do
+            -- not sending update events, one event at the end, based on the
+            -- post of the new entry should suffice to reload only once
+            dao_factory.targets:delete(
+              { id = entry.id }, 
+              { quiet = true }
+            )
+            -- ignoring errors here, deleted by id, so should not matter
+            -- in case another kong-node does the same cleanup simultaneously
+            cnt = cnt + 1 
+          end
+
+          ngx.log(ngx.INFO, "[admin api] Finished cleanup of target table",
+            " for upstream ", tostring(self.params.upstream_id),
+            " removed ", tostring(cnt), " target entries")
+        end
+      end
+
+      crud.post(self.params, dao_factory.targets)
+    end,
+  },
+}
diff --git a/kong/core/balancer.lua b/kong/core/balancer.lua
index 7b3e0079f03d..f185eba9ac2d 100644
--- a/kong/core/balancer.lua
+++ b/kong/core/balancer.lua
@@ -1,41 +1,241 @@
-local dns_client = require "resty.dns.client"
+local cache = require "kong.tools.database_cache"
+local pl_tablex = require "pl.tablex"
+local responses = require "kong.tools.responses"
+local singletons = require "kong.singletons"
+local dns_client = require "resty.dns.client"  -- due to startup/require order, cannot use the one from 'singletons' here
+local ring_balancer = require "resty.dns.balancer"
 
 local toip = dns_client.toip
+local log = ngx.log
 
--- looks up a balancer for the target.
--- @param target the table with the target details
--- @return balancer if found, or nil if not found, or nil+error on error
-local get_balancer = function(target)
-  return nil  -- TODO: place holder, forces dns use to first fix regression
+local ERROR = ngx.ERR
+local DEBUG = ngx.DEBUG
+local EMPTY_T = pl_tablex.readonly {}
+
+--===========================================================
+-- Ring-balancer based resolution
+--===========================================================
+local balancers = {}  -- table holding our balancer objects, indexed by upstream name
+
+-- caching logic;
+-- we retain 3 entities:
+-- 1) list of upstreams: to be invalidated on any upstream change
+-- 2) individual upstreams: to be invalidated on individual basis
+-- 3) target history for an upstream, invalidated when:
+--    a) along with the upstream it belongs to
+--    b) upon any target change for the upstream (can only add entries)
+-- Distinction between 1 and 2 makes it possible to invalidate individual
+-- upstreams, instead of all at once forcing to rebuild all balancers
+
+-- Implements a simple dictionary with all upstream-ids indexed
+-- by their name. 
+local function load_upstreams_dict_into_memory()
+  log(DEBUG, "fetching all upstreams")
+  local upstreams, err = singletons.dao.upstreams:find_all()
+  if err then
+    return nil, err
+  end
+  
+  -- build a dictionary, indexed by the upstream name
+  local upstreams_dict = {}
+  for _, up in ipairs(upstreams) do
+    upstreams_dict[up.name] = up.id
+  end
+
+  -- check whether any of our existing balancers has been deleted
+  for upstream_name in pairs(balancers) do
+    if not upstreams_dict[upstream_name] then
+      -- this one was deleted, so also clear the balancer object
+      balancers[upstream_name] = nil
+    end
+  end
+
+  return upstreams_dict
+end
+
+-- delete a balancer object from our internal cache
+local function invalidate_balancer(upstream_name)
+  balancers[upstream_name] = nil
 end
 
+-- loads a single upstream entity
+local function load_upstream_into_memory(upstream_id)
+  log(DEBUG, "fetching upstream: ", tostring(upstream_id))
 
-local first_try_balancer = function(target)
+  local upstream, err = singletons.dao.upstreams:find_all {id = upstream_id}
+  if not upstream then
+    return nil, err
+  end
+  
+  return upstream[1]  -- searched by id, so only 1 row in the returned set
 end
 
-local retry_balancer = function(target)
+-- finds and returns an upstream entity. This functions covers
+-- caching, invalidation, db access, et al.
+-- @return upstream table, or `false` if not found, or nil+error
+local function get_upstream(upstream_name)
+  local upstreams_dict, err = cache.get_or_set(cache.upstreams_dict_key(), 
+                              nil, load_upstreams_dict_into_memory)
+  if err then
+    return nil, err
+  end
+
+  local upstream_id = upstreams_dict[upstream_name]
+  if not upstream_id then
+    return false -- no upstream by this name
+  end
+
+  return cache.get_or_set(cache.upstream_key(upstream_id), nil,
+                          load_upstream_into_memory, upstream_id)
 end
 
-local first_try_dns = function(target)
-  local ip, port = toip(target.upstream.host, target.upstream.port, false)
-  if not ip then
-    return nil, port
+-- loads the target history for an upstream
+-- @param upstream_id Upstream uuid for which to load the target history
+local function load_targets_into_memory(upstream_id)
+  log(DEBUG, "fetching targets for upstream: ",tostring(upstream_id))
+
+  local target_history, err = singletons.dao.targets:find_all {upstream_id = upstream_id}
+  if err then return nil, err end
+  
+  -- perform some raw data updates
+  for _, target in ipairs(target_history) do
+    -- split `target` field into `name` and `port`
+    local port
+    target.name, port = string.match(target.target, "^(.-):(%d+)$")
+    target.port = tonumber(port)
+
+    -- need exact order, so create sort-key by created-time and uuid
+    target.order = target.created_at .. ":" .. target.id
   end
-  target.ip = ip
-  target.port = port
-  return true
+
+  table.sort(target_history, function(a,b) 
+    return a.order < b.order
+  end)
+
+  return target_history
 end
 
-local retry_dns = function(target)
-  local ip, port = toip(target.upstream.host, target.upstream.port, true)
-  if type(ip) ~= "string" then
-    return nil, port
+-- applies the history of lb transactions from index `start` forward
+-- @param rb ring-balancer object
+-- @param history list of targets/transactions to be applied
+-- @param start the index where to start in the `history` parameter
+-- @return true
+local function apply_history(rb, history, start)
+
+  for i = start, #history do 
+    local target = history[i]
+
+    if target.weight > 0 then
+      assert(rb:addHost(target.name, target.port, target.weight))
+    else
+      assert(rb:removeHost(target.name, target.port))
+    end
+
+    rb.__targets_history[i] = {
+      name = target.name,
+      port = target.port,
+      weight = target.weight,
+      order = target.order,
+    }
   end
-  target.ip = ip
-  target.port = port
+
   return true
 end
 
+-- looks up a balancer for the target.
+-- @param target the table with the target details
+-- @return balancer if found, or `false` if not found, or nil+error on error
+local get_balancer = function(target)
+  -- NOTE: only called upon first lookup, so `cache_only` limitations do not apply here
+  local hostname = target.upstream.host
+  
+  -- first go and find the upstream object, from cache or the db
+  local upstream, err = get_upstream(hostname)
+
+  if upstream == false then
+    return false                -- no upstream by this name
+  end
+
+  if err then
+    return nil, err             -- there was an error
+  end
+
+  -- we've got the upstream, now fetch its targets, from cache or the db
+  local targets_history, err = cache.get_or_set(cache.targets_key(upstream.id), 
+                               nil, load_targets_into_memory, upstream.id)
+  if err then
+    return nil, err
+  end
+
+  local balancer = balancers[upstream.name]
+  if not balancer then
+    -- no balancer yet (or invalidated) so create a new one
+    balancer, err = ring_balancer.new({
+        wheelsize = upstream.slots,
+        order = upstream.orderlist,
+        dns = dns_client,
+      })
+
+    if not balancer then
+      return balancer, err
+    end
+
+    -- NOTE: we're inserting a foreign entity in the balancer, to keep track of
+    -- target-history changes!
+    balancer.__targets_history = {}
+    balancers[upstream.name] = balancer
+  end
+
+  -- check history state
+  -- NOTE: in the code below variables are similarly named, but the
+  -- ones with `__`-prefixed, are the ones on the `balancer` object, and the
+  -- regular ones are the ones we just fetched and are comparing against.
+  local __size = #balancer.__targets_history
+  local size = #targets_history
+
+  if __size ~= size or
+    (balancer.__targets_history[__size] or EMPTY_T).order ~=
+    (targets_history[size] or EMPTY_T).order then
+    -- last entries in history don't match, so we must do some updates.
+
+    -- compare balancer history with db-loaded history
+    local last_equal_index = 0  -- last index where history is the same
+    for i, entry in ipairs(balancer.__targets_history) do
+      if entry.order ~= (targets_history[i] or EMPTY_T).order then
+        last_equal_index = i - 1
+        break
+      end
+    end
+
+    if last_equal_index == __size then
+      -- history is the same, so we only need to add new entries
+      apply_history(balancer, targets_history, last_equal_index + 1)
+
+    else
+      -- history not the same.
+      -- TODO: ideally we would undo the last ones until we're equal again
+      -- and can replay changes, but not supported by ring-balancer yet.
+      -- for now; create a new balancer from scratch
+      balancer, err = ring_balancer.new({
+          wheelsize = upstream.slots,
+          order = upstream.orderlist,
+          dns = dns_client,
+        })
+      if not balancer then return balancer, err end
+
+      balancer.__targets_history = {}
+      balancers[upstream.name] = balancer  -- overwrite our existing one
+      apply_history(balancer, targets_history, 1)
+    end
+  end
+  
+  return balancer
+end
+
+
+--===========================================================
+-- Main entry point when resolving
+--===========================================================
 
 -- Resolves the target structure in-place (fields `ip` and `port`).
 --
@@ -45,35 +245,75 @@ end
 -- @param target the data structure as defined in `core.access.before` where it is created
 -- @return true on success, nil+error otherwise
 local function execute(target)
+  local upstream = target.upstream
+
   if target.type ~= "name" then
     -- it's an ip address (v4 or v6), so nothing we can do...
-    target.ip = target.upstream.host
-    target.port = target.upstream.port or 80
+    target.ip = upstream.host
+    target.port = upstream.port or 80  -- TODO: remove this fallback value
     return true
   end
-  
+
   -- when tries == 0 it runs before the `balancer` context (in the `access` context),
   -- when tries >= 2 then it performs a retry in the `balancer` context
-  if target.tries == 0 then
+  local dns_cache_only = target.tries ~= 0
+  local balancer
+
+  if dns_cache_only then
+    -- retry, so balancer is already set if there was one
+    balancer = target.balancer
+
+  else
     local err
     -- first try, so try and find a matching balancer/upstream object
-    target.balancer, err = get_balancer(target)
-    if err then return nil, err end
-
-    if target.balancer then
-      return first_try_balancer(target)
-    else
-      return first_try_dns(target)
+    balancer, err = get_balancer(target)
+    if err then -- check on err, `nil` without `err` means we do dns resolution
+      return nil, err
     end
-  else
-    if target.balancer then
-      return retry_balancer(target)
-    else
-      return retry_dns(target)
+
+    -- store for retries
+    target.balancer = balancer
+  end
+  
+  if balancer then
+    -- have to invoke the ring-balancer
+    local hashValue = nil  -- TODO: implement, nil does simple round-robin
+    
+    local ip, port, hostname = balancer:getPeer(hashValue, dns_cache_only)
+    if not ip then
+      if port == "No peers are available" then
+        -- in this case a "503 service unavailable", others will be a 500.
+        log(ERROR, "failure to get a peer from the ring-balancer '",
+                   upstream.host, "'; ", port)
+        return responses.send(503)
+      end
+
+      return nil, port -- some other error
     end
+
+    target.ip = ip
+    target.port = port
+    target.hostname = hostname
+    return true
   end
+
+  -- have to do a regular DNS lookup
+  local ip, port = toip(upstream.host, upstream.port, dns_cache_only)
+  if not ip then
+    return nil, port
+  end
+
+  target.ip = ip
+  target.port = port
+  return true
 end
 
 return { 
   execute = execute,
+  invalidate_balancer = invalidate_balancer,
+ 
+  -- ones below are exported for test purposes
+  _load_upstreams_dict_into_memory = load_upstreams_dict_into_memory,
+  _load_upstream_into_memory = load_upstream_into_memory,
+  _load_targets_into_memory = load_targets_into_memory,
 }
\ No newline at end of file
diff --git a/kong/core/handler.lua b/kong/core/handler.lua
index 7a4372723e66..2b94429cc043 100644
--- a/kong/core/handler.lua
+++ b/kong/core/handler.lua
@@ -43,7 +43,7 @@ return {
       ngx.ctx.api, ngx.ctx.upstream_url, upstream_host, upstream_table = resolve(ngx.var.request_uri, ngx.req.get_headers())
       
       balancer_address = {
-        upstream = upstream_table,                       -- original parsed upstream url from the resolver
+        upstream = upstream_table,                       -- original parsed upstream url from the Kong api resolver/router
         type = utils.hostname_type(upstream_table.host), -- the type of `upstream.host`; ipv4, ipv6 or name
         tries = 0,                                       -- retry counter
     --  ip = nil,                                        -- final target IP address
@@ -51,15 +51,25 @@ return {
         retries = ngx.ctx.api.retries,                   -- number of retries for the balancer
         -- health data, see https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/balancer.md#get_last_failure
     --  failures = nil,                                  -- for each failure an entry { name = "...", code = xx }
-    --  balancer = nil,                                  -- the balancer object, in case of a balancer
+        -- in case of ring-balancer
+    --  balancer = nil,                                  -- the balancer object
+    --  hostname = nil,                                  -- the hostname that belongs to the ip address returned by the balancer
       }
       ngx.ctx.balancer_address = balancer_address
-      ngx.var.upstream_host = upstream_host
+
       local ok, err = balancer_execute(balancer_address)
       if not ok then
-        ngx.log(ngx.ERR, "failed the initial dns/balancer resolve: ", err)
-        return responses.send_HTTP_INTERNAL_SERVER_ERROR()
+        return responses.send_HTTP_INTERNAL_SERVER_ERROR("failed the initial "..
+          "dns/balancer resolve for '"..balancer_address.upstream.host..
+          "' with: "..tostring(err))
       end
+
+      if balancer_address.hostname and not ngx.ctx.api.preserve_host then
+        ngx.var.upstream_host = balancer_address.hostname
+      else
+        ngx.var.upstream_host = upstream_host
+      end
+
     end,
     -- Only executed if the `resolver` module found an API and allows nginx to proxy it.
     after = function()
diff --git a/kong/core/hooks.lua b/kong/core/hooks.lua
index 3852e7486859..38c7aaf402b7 100644
--- a/kong/core/hooks.lua
+++ b/kong/core/hooks.lua
@@ -1,6 +1,7 @@
 local events = require "kong.core.events"
 local cache = require "kong.tools.database_cache"
 local utils = require "kong.tools.utils"
+local balancer = require "kong.core.balancer"
 local singletons = require "kong.singletons"
 local pl_stringx = require "pl.stringx"
 
@@ -19,6 +20,17 @@ local function invalidate(message_t)
   elseif message_t.collection == "plugins" then
     -- Handles both the update and the delete
     invalidate_plugin(message_t.old_entity and message_t.old_entity or message_t.entity)
+  elseif message_t.collection == "targets" then
+    -- targets only append new entries, we're not changing anything
+    -- but we need to reload the related upstreams target-history, so invalidate
+    -- that instead of the target
+    cache.delete(cache.targets_key(message_t.entity.upstream_id))
+  elseif message_t.collection == "upstreams" then
+    --we invalidate the list, the individual upstream, and its target history
+    cache.delete(cache.upstreams_dict_key())
+    cache.delete(cache.upstream_key(message_t.entity.id))
+    cache.delete(cache.targets_key(message_t.entity.id))
+    balancer.invalidate_balancer(message_t.entity.name)
   end
 end
 
diff --git a/kong/dao/db/cassandra.lua b/kong/dao/db/cassandra.lua
index 38e6a41e44ed..45557951e078 100644
--- a/kong/dao/db/cassandra.lua
+++ b/kong/dao/db/cassandra.lua
@@ -24,7 +24,8 @@ _M.dao_insert_values = {
     return uuid()
   end,
   timestamp = function()
-    return timestamp.get_utc()
+    -- return time in UNIT millisecond, and PRECISION millisecond 
+    return math.floor(timestamp.get_utc_ms()) 
   end
 }
 
diff --git a/kong/dao/db/postgres.lua b/kong/dao/db/postgres.lua
index dbd4aa4518be..4c6a3b3c92ee 100644
--- a/kong/dao/db/postgres.lua
+++ b/kong/dao/db/postgres.lua
@@ -103,7 +103,7 @@ local function ttl(self, tbl, table_name, schema, ttl)
   local primary_key_type, err = retrieve_primary_key_type(self, schema, table_name)
   if not primary_key_type then return nil, err end
 
-  -- get current server time
+  -- get current server time, in milliseconds, but with SECOND precision
   local query = [[
     SELECT extract(epoch from now() at time zone 'utc')::bigint*1000 as timestamp;
   ]]
@@ -203,7 +203,7 @@ local function get_select_fields(schema)
   local fields = {}
   for k, v in pairs(schema.fields) do
     if v.type == "timestamp" then
-      fields[#fields+1] = fmt("extract(epoch from %s)::bigint*1000 as %s", k, k)
+      fields[#fields+1] = fmt("(extract(epoch from %s)*1000)::bigint as %s", k, k)
     else
       fields[#fields+1] = '"' .. k .. '"'
     end
@@ -299,7 +299,7 @@ local function deserialize_timestamps(self, row, schema)
   for k, v in pairs(schema.fields) do
     if v.type == "timestamp" and result[k] then
       local query = fmt([[
-        SELECT extract(epoch from timestamp '%s')::bigint*1000 as %s;
+        SELECT (extract(epoch from timestamp '%s')*1000)::bigint as %s;
       ]], result[k], k)
       local res, err = self:query(query)
       if not res then return nil, err
diff --git a/kong/dao/factory.lua b/kong/dao/factory.lua
index 490cd38614f9..2c3d7dfceb74 100644
--- a/kong/dao/factory.lua
+++ b/kong/dao/factory.lua
@@ -2,7 +2,7 @@ local DAO = require "kong.dao.dao"
 local utils = require "kong.tools.utils"
 local ModelFactory = require "kong.dao.model_factory"
 
-local CORE_MODELS = {"apis", "consumers", "plugins", "nodes"}
+local CORE_MODELS = {"apis", "consumers", "plugins", "nodes", "upstreams", "targets"}
 
 -- returns db errors as strings, including the initial `nil`
 local function ret_error_string(db_name, res, err)
diff --git a/kong/dao/migrations/cassandra.lua b/kong/dao/migrations/cassandra.lua
index 2bdfe8b93bc8..a06cf9df3a25 100644
--- a/kong/dao/migrations/cassandra.lua
+++ b/kong/dao/migrations/cassandra.lua
@@ -178,6 +178,40 @@ return {
       end
     end,
     down = nil, 
-  }
+  },
+  {
+    name = "2016-09-16-141423_upstreams",
+    -- Note on the timestamps;
+    -- The Cassandra timestamps are created in Lua code, and hence ALL entities
+    -- will now be created in millisecond precision. The existing entries will
+    -- remain in second precision, but new ones (for ALL entities!) will be
+    -- in millisecond precision.
+    -- This differs from the Postgres one where only the new entities (upstreams 
+    -- and targets) will get millisecond precision.
+    up = [[
+      CREATE TABLE IF NOT EXISTS upstreams(
+        id uuid,
+        name text,
+        slots int,
+        orderlist text,
+        created_at timestamp,
+        PRIMARY KEY (id)
+      );
+      CREATE INDEX IF NOT EXISTS ON upstreams(name);
+      CREATE TABLE IF NOT EXISTS targets(
+        id uuid,
+        target text,
+        weight int,
+        upstream_id uuid,
+        created_at timestamp,
+        PRIMARY KEY (id)
+      );
+      CREATE INDEX IF NOT EXISTS ON targets(upstream_id);
+    ]],
+    down = [[
+      DROP TABLE upstreams;
+      DROP TABLE targets;
+    ]],
+  },
 }
 
diff --git a/kong/dao/migrations/postgres.lua b/kong/dao/migrations/postgres.lua
index d7a19aff789e..8a18923cfe29 100644
--- a/kong/dao/migrations/postgres.lua
+++ b/kong/dao/migrations/postgres.lua
@@ -156,4 +156,42 @@ return {
       ALTER TABLE apis DROP COLUMN IF EXISTS retries;
     ]]
   },
+  {
+    name = "2016-09-16-141423_upstreams",
+    -- Note on the timestamps below; these use a precision of milliseconds
+    -- this differs from the other tables above, as they only use second precision.
+    -- This differs from the change to the Cassandra entities.
+    up = [[
+      CREATE TABLE IF NOT EXISTS upstreams(
+        id uuid PRIMARY KEY,
+        name text UNIQUE,
+        slots int NOT NULL,
+        orderlist text NOT NULL,
+        created_at timestamp without time zone default (CURRENT_TIMESTAMP(3) at time zone 'utc')
+      );
+      DO $$
+      BEGIN
+        IF (SELECT to_regclass('upstreams_name_idx')) IS NULL THEN
+          CREATE INDEX upstreams_name_idx ON upstreams(name);
+        END IF;
+      END$$;
+      CREATE TABLE IF NOT EXISTS targets(
+        id uuid PRIMARY KEY,
+        target text NOT NULL,
+        weight int NOT NULL,
+        upstream_id uuid REFERENCES upstreams(id) ON DELETE CASCADE,
+        created_at timestamp without time zone default (CURRENT_TIMESTAMP(3) at time zone 'utc')
+      );
+      DO $$
+      BEGIN
+        IF (SELECT to_regclass('targets_target_idx')) IS NULL THEN
+          CREATE INDEX targets_target_idx ON targets(target);
+        END IF;
+      END$$;
+    ]],
+    down = [[
+      DROP TABLE upstreams;
+      DROP TABLE targets;
+    ]],
+  },
 }
diff --git a/kong/dao/schemas/targets.lua b/kong/dao/schemas/targets.lua
new file mode 100644
index 000000000000..1550030e2fc6
--- /dev/null
+++ b/kong/dao/schemas/targets.lua
@@ -0,0 +1,68 @@
+-- This schema defines a sequential list of updates to the upstream/loadbalancer algorithm
+-- hence entries cannot be deleted or modified. Only new ones appended that will overrule
+-- previous entries.
+
+local Errors = require "kong.dao.errors"
+local utils = require "kong.tools.utils"
+
+local DEFAULT_PORT = 8000
+local DEFAULT_WEIGHT = 100
+local WEIGHT_MIN, WEIGHT_MAX = 0, 1000
+local WEIGHT_MSG = "weight must be from "..WEIGHT_MIN.." to "..WEIGHT_MAX
+
+return {
+  table = "targets",
+  primary_key = {"id"},
+  fields = {
+    id = {
+      type = "id", 
+      dao_insert_value = true, 
+      required = true,
+    },
+    created_at = {
+      type = "timestamp", 
+      immutable = true, 
+      dao_insert_value = true, 
+      required = true,
+    },
+    upstream_id = {
+      type = "id",
+      foreign = "upstreams:id"
+    },
+    target = {
+      -- in 'hostname:port' format, if omitted default port will be inserted
+      type = "string",
+      required = true,
+    },
+    weight = {
+      -- weight in the loadbalancer algorithm.
+      -- to disable an entry, set the weight to 0
+      type = "number",
+      default = DEFAULT_WEIGHT,
+    },
+  },
+  self_check = function(schema, config, dao, is_updating)
+    
+    -- check weight
+    if config.weight < WEIGHT_MIN or config.weight > WEIGHT_MAX then
+      return false, Errors.schema(WEIGHT_MSG)
+    end
+
+    -- check the target
+    local p = utils.normalize_ip(config.target)
+    if not p then
+      return false, Errors.schema("Invalid target; not a valid hostname or ip address")
+    end
+    config.target = utils.format_host(p, DEFAULT_PORT)
+
+    return true
+  end,
+  marshall_event = function(self, t)
+    -- when sending cluster events, we must include the upstream id, as the 
+    -- upstream cache needs to be invalidated, not the target itself.
+    return {
+      id = t.id,
+      upstream_id = t.upstream_id,
+    }
+  end
+}
diff --git a/kong/dao/schemas/upstreams.lua b/kong/dao/schemas/upstreams.lua
new file mode 100644
index 000000000000..d4dac408b245
--- /dev/null
+++ b/kong/dao/schemas/upstreams.lua
@@ -0,0 +1,120 @@
+local Errors = require "kong.dao.errors"
+local utils = require "kong.tools.utils"
+
+local DEFAULT_SLOTS = 100
+local SLOTS_MIN, SLOTS_MAX = 10, 2^16
+local SLOTS_MSG = "number of slots must be between "..SLOTS_MIN.." and "..SLOTS_MAX
+
+return {
+  table = "upstreams",
+  primary_key = {"id", "name"},
+  fields = {
+    id = {
+      type = "id", 
+      dao_insert_value = true, 
+      required = true,
+    },
+    created_at = {
+      type = "timestamp", 
+      immutable = true, 
+      dao_insert_value = true, 
+      required = true,
+    },
+    name = {
+      -- name is a hostname like name that can be referenced in an `upstream_url` field
+      type = "string", 
+      unique = true, 
+      required = true,
+    },
+    slots = {
+      -- the number of slots in the loadbalancer algorithm
+      type = "number",
+      default = DEFAULT_SLOTS,
+    },
+    orderlist = {
+      -- a list of sequential, but randomly ordered, integer numbers. In the datastore
+      -- because all Kong nodes need the exact-same 'randomness'. If changed, consistency is lost.
+      -- must have exactly `slots` number of entries.
+      type = "array",
+      default = {},
+    }
+  },
+  self_check = function(schema, config, dao, is_updating)
+    
+    -- check the name
+    local p = utils.normalize_ip(config.name)
+    if not p then
+      return false, Errors.schema("Invalid name; must be a valid hostname")
+    end
+    if p.type ~= "name" then
+      return false, Errors.schema("Invalid name; no ip addresses allowed")
+    end
+    if p.port then
+      return false, Errors.schema("Invalid name; no port allowed")
+    end
+    
+    -- check the slots number
+    if config.slots < SLOTS_MIN or config.slots > SLOTS_MAX then
+      return false, Errors.schema(SLOTS_MSG)
+    end
+    
+    -- check the order array
+    local order = config.orderlist
+    if #order == config.slots then
+      -- array size unchanged, check consistency
+
+      local t = utils.shallow_copy(order)
+      table.sort(t)
+      local count, max = 0, 0
+      for i, v in pairs(t) do
+        if (i ~= v) then
+          return false, Errors.schema("invalid orderlist")
+        end
+
+        count = count + 1
+        if i > max then max = i end
+      end
+
+      if (count ~= config.slots) or (max ~= config.slots) then
+        return false, Errors.schema("invalid orderlist")
+      end
+
+    else
+      -- size mismatch
+      if #order > 0 then
+        -- size given, but doesn't match the size of the also given orderlist
+        return false, Errors.schema("size mismatch between 'slots' and 'orderlist'")
+      end
+
+      -- No list given, generate order array
+      local t = {}
+      for i = 1, config.slots do
+        t[i] = {
+          id = i, 
+          order = math.random(1, config.slots),
+        }
+      end
+
+      -- sort the array (we don't check for -accidental- duplicates as the 
+      -- id field is used for the order and that one is always unique)
+      table.sort(t, function(a,b) 
+        return a.order < b.order
+      end)
+
+      -- replace the created 'record' with only the id
+      for i, v in ipairs(t) do
+        t[i] = v.id
+      end
+      
+      config.orderlist = t
+    end
+
+    return true
+  end,
+  marshall_event = function(self, t)
+    return {
+      id = t.id,
+      name = t.name,
+    }
+  end
+}
diff --git a/kong/kong.lua b/kong/kong.lua
index aed08346267c..ce5d20179410 100644
--- a/kong/kong.lua
+++ b/kong/kong.lua
@@ -207,8 +207,9 @@ function Kong.balancer()
     
     local ok, err = balancer_execute(addr)
     if not ok then
-      ngx.log(ngx.ERR, "failed to retry the balancer/resolver: ", err)
-      return responses.send_HTTP_INTERNAL_SERVER_ERROR()
+      return responses.send_HTTP_INTERNAL_SERVER_ERROR("failed to retry the "..
+        "dns/balancer resolver for '"..addr.upstream.host..
+        "' with: "..tostring(err))
     end
   else
     -- first try, so set the max number of retries
diff --git a/kong/tools/database_cache.lua b/kong/tools/database_cache.lua
index 489865f36d0d..5d90010bad86 100644
--- a/kong/tools/database_cache.lua
+++ b/kong/tools/database_cache.lua
@@ -21,7 +21,9 @@ local CACHE_KEYS = {
   SSL = "ssl",
   ALL_APIS_BY_DIC = "ALL_APIS_BY_DIC",
   LDAP_CREDENTIAL = "ldap_credentials",
-  BOT_DETECTION = "bot_detection"
+  BOT_DETECTION = "bot_detection",
+  UPSTREAMS = "upstreams",
+  TARGETS = "targets",
 }
 
 local _M = {}
@@ -224,6 +226,18 @@ function _M.bot_detection_key(key)
   return CACHE_KEYS.BOT_DETECTION..":"..key
 end
 
+function _M.upstreams_dict_key()
+  return CACHE_KEYS.UPSTREAMS
+end
+
+function _M.upstream_key(upstream_id)
+  return CACHE_KEYS.UPSTREAMS..":"..upstream_id
+end
+
+function _M.targets_key(upstream_id)
+  return CACHE_KEYS.TARGETS..":"..upstream_id
+end
+
 function _M.all_apis_by_dict_key()
   return CACHE_KEYS.ALL_APIS_BY_DIC
 end
diff --git a/spec/01-unit/08-entities_schemas_spec.lua b/spec/01-unit/08-entities_schemas_spec.lua
index f3e443eba697..8176ddd9ca46 100644
--- a/spec/01-unit/08-entities_schemas_spec.lua
+++ b/spec/01-unit/08-entities_schemas_spec.lua
@@ -1,16 +1,19 @@
 local api_schema = require "kong.dao.schemas.apis"
 local consumer_schema = require "kong.dao.schemas.consumers"
 local plugins_schema = require "kong.dao.schemas.plugins"
+local targets_schema = require "kong.dao.schemas.targets"
+local upstreams_schema = require "kong.dao.schemas.upstreams"
 local validations = require "kong.dao.schemas_validation"
 local validate_entity = validations.validate_entity
-
---require "kong.tools.ngx_stub"
+local utils = require "kong.tools.utils"
 
 describe("Entities Schemas", function()
 
   for k, schema in pairs({api = api_schema,
                           consumer = consumer_schema,
-                          plugins = plugins_schema}) do
+                          plugins = plugins_schema,
+                          targets = targets_schema,
+                          upstreams = upstreams_schema}) do
     it(k.." schema should have some required properties", function()
       assert.is_table(schema.primary_key)
       assert.is_table(schema.fields)
@@ -25,7 +28,7 @@ describe("Entities Schemas", function()
   describe("APIs", function()
     it("should refuse an empty object", function()
       local valid, errors = validate_entity({}, api_schema)
-      assert.False(valid)
+      assert.is_false(valid)
       assert.truthy(errors)
     end)
 
@@ -35,7 +38,7 @@ describe("Entities Schemas", function()
           local t = {name = name, upstream_url = "http://mockbin.com", request_host = "mockbin.com"}
 
           local valid, errors = validate_entity(t, api_schema)
-          assert.False(valid)
+          assert.is_false(valid)
           assert.truthy(errors)
           assert.equal("name must only contain alphanumeric and '., -, _, ~' characters", errors.name)
         end
@@ -49,7 +52,7 @@ describe("Entities Schemas", function()
           request_host = "mockbin.com",
           upstream_url = "asdasd"
         }, api_schema)
-        assert.False(valid)
+        assert.is_false(valid)
         assert.equal("upstream_url is not a url", errors.upstream_url)
       end)
       it("should return error with wrong upstream_url protocol", function()
@@ -58,7 +61,7 @@ describe("Entities Schemas", function()
           request_host = "mockbin.com",
           upstream_url = "wot://mockbin.com/"
         }, api_schema)
-        assert.False(valid)
+        assert.is_false(valid)
         assert.equal("Supported protocols are HTTP and HTTPS", errors.upstream_url)
       end)
       it("should validate with upper case protocol", function()
@@ -68,7 +71,7 @@ describe("Entities Schemas", function()
           upstream_url = "HTTP://mockbin.com/world"
         }, api_schema)
         assert.falsy(errors)
-        assert.True(valid)
+        assert.is_true(valid)
       end)
     end)
 
@@ -77,7 +80,7 @@ describe("Entities Schemas", function()
         local t = {request_host = "", upstream_url = "http://mockbin.com", name = "mockbin"}
 
         local valid, errors = validate_entity(t, api_schema)
-        assert.False(valid)
+        assert.is_false(valid)
         assert.equal("At least a 'request_host' or a 'request_path' must be specified", errors.request_host)
         assert.equal("At least a 'request_host' or a 'request_path' must be specified", errors.request_path)
       end)
@@ -92,7 +95,7 @@ describe("Entities Schemas", function()
           local valid, errors = validate_entity(t, api_schema)
           assert.equal("Invalid value: "..v, (errors and errors.request_host or ""))
           assert.falsy(errors.request_path)
-          assert.False(valid)
+          assert.is_false(valid)
         end
       end)
       it("should accept valid request_host", function()
@@ -110,7 +113,7 @@ describe("Entities Schemas", function()
           local t = {request_host = v, upstream_url = "http://mockbin.com", name = "mockbin"}
           local valid, errors = validate_entity(t, api_schema)
           assert.falsy(errors)
-          assert.True(valid)
+          assert.is_true(valid)
         end
       end)
       it("should accept valid wildcard request_host", function()
@@ -120,7 +123,7 @@ describe("Entities Schemas", function()
           local t = {request_host = v, upstream_url = "http://mockbin.com", name = "mockbin"}
           local valid, errors = validate_entity(t, api_schema)
           assert.falsy(errors)
-          assert.True(valid)
+          assert.is_true(valid)
         end
       end)
       it("should refuse request_host with more than one wildcard", function()
@@ -131,7 +134,7 @@ describe("Entities Schemas", function()
         }
 
         local valid, errors = validate_entity(api_t, api_schema)
-        assert.False(valid)
+        assert.is_false(valid)
         assert.equal("Only one wildcard is allowed: *.mockbin.*", errors.request_host)
       end)
       it("should refuse invalid wildcard request_host placement", function()
@@ -141,7 +144,7 @@ describe("Entities Schemas", function()
           local t = {request_host = v, upstream_url = "http://mockbin.com", name = "mockbin"}
           local valid, errors = validate_entity(t, api_schema)
           assert.equal("Invalid wildcard placement: "..v, (errors and errors.request_host or ""))
-          assert.False(valid)
+          assert.is_false(valid)
         end
       end)
       it("should refuse invalid wildcard request_host", function()
@@ -156,7 +159,7 @@ describe("Entities Schemas", function()
           local valid, errors = validate_entity(t, api_schema)
           assert.equal("Invalid value: "..v, (errors and errors.request_host or ""))
           assert.falsy(errors.request_path)
-          assert.False(valid)
+          assert.is_false(valid)
         end
       end)
     end)
@@ -166,7 +169,7 @@ describe("Entities Schemas", function()
         local t = {request_path = "", upstream_url = "http://mockbin.com"}
 
         local valid, errors = validate_entity(t, api_schema)
-        assert.False(valid)
+        assert.is_false(valid)
         assert.equal("At least a 'request_host' or a 'request_path' must be specified", errors.request_host)
         assert.equal("At least a 'request_host' or a 'request_path' must be specified", errors.request_path)
       end)
@@ -176,7 +179,7 @@ describe("Entities Schemas", function()
         for _, v in ipairs(invalids) do
           local t = {request_path = v, upstream_url = "http://mockbin.com", name = "mockbin"}
           local valid, errors = validate_entity(t, api_schema)
-          assert.False(valid)
+          assert.is_false(valid)
           assert.equal("must only contain alphanumeric and '., -, _, ~, /, %' characters", errors.request_path)
         end
       end)
@@ -187,7 +190,7 @@ describe("Entities Schemas", function()
           local t = {request_path = v, upstream_url = "http://mockbin.com", name = "mockbin"}
           local valid, errors = validate_entity(t, api_schema)
           assert.falsy(errors)
-          assert.True(valid)
+          assert.is_true(valid)
         end
       end)
       it("should not accept bad %-encoded characters", function()
@@ -203,7 +206,7 @@ describe("Entities Schemas", function()
         for i, v in ipairs(invalids) do
           local t = {request_path = v, upstream_url = "http://mockbin.com", name = "mockbin"}
           local valid, errors = validate_entity(t, api_schema)
-          assert.False(valid)
+          assert.is_false(valid)
           assert.equal("must use proper encoding; '"..errstr[i].."' is invalid", errors.request_path)
         end
       end)
@@ -213,7 +216,7 @@ describe("Entities Schemas", function()
           local t = {request_path = v, upstream_url = "http://mockbin.com", name = "mockbin"}
           local valid, errors = validate_entity(t, api_schema)
           assert.falsy(errors)
-          assert.True(valid)
+          assert.is_true(valid)
         end
       end)
       it("should not accept without prefix slash", function()
@@ -222,7 +225,7 @@ describe("Entities Schemas", function()
         for _, v in ipairs(invalids) do
           local t = {request_path = v, upstream_url = "http://mockbin.com", name = "mockbin"}
           local valid, errors = validate_entity(t, api_schema)
-          assert.False(valid)
+          assert.is_false(valid)
           assert.equal("must be prefixed with slash: '"..v.."'", errors.request_path)
         end
       end)
@@ -233,7 +236,7 @@ describe("Entities Schemas", function()
           upstream_url = "http://mockbin.com"
         }, api_schema)
         assert.falsy(errors)
-        assert.True(valid)
+        assert.is_true(valid)
       end)
       it("should not accept invalid URI", function()
         local invalids = {"//status", "/status//123", "/status/123//"}
@@ -241,7 +244,7 @@ describe("Entities Schemas", function()
         for _, v in ipairs(invalids) do
           local t = {request_path = v, upstream_url = "http://mockbin.com", name = "mockbin"}
           local valid, errors = validate_entity(t, api_schema)
-          assert.False(valid)
+          assert.is_false(valid)
           assert.equal("invalid: '"..v.."'", errors.request_path)
         end
       end)
@@ -253,7 +256,7 @@ describe("Entities Schemas", function()
           local valid, errors = validate_entity(t, api_schema)
           assert.falsy(errors)
           assert.equal(string.sub(v, 1, -2), t.request_path)
-          assert.True(valid)
+          assert.is_true(valid)
         end
       end)
     end)
@@ -265,7 +268,7 @@ describe("Entities Schemas", function()
           local t = {request_host = "mydomain.com", upstream_url = "http://mockbin.com", name = "mockbin", retries = v}
           local valid, errors = validate_entity(t, api_schema)
           assert.falsy(errors)
-          assert.True(valid)
+          assert.is_true(valid)
         end
       end)
       it("rejects invalid values", function()
@@ -273,7 +276,7 @@ describe("Entities Schemas", function()
         for _, v in ipairs(valids) do
           local t = {request_host = "mydomain.com", upstream_url = "http://mockbin.com", name = "mockbin", retries = v}
           local valid, errors = validate_entity(t, api_schema)
-          assert.False(valid)
+          assert.is_false(valid)
           assert.equal("retries must be an integer, from 0 to 32767", errors.retries)
         end
       end)
@@ -285,14 +288,14 @@ describe("Entities Schemas", function()
         upstream_url = "http://mockbin.com"
       }, api_schema)
       assert.falsy(errors)
-      assert.True(valid)
+      assert.is_true(valid)
     end)
 
     it("should complain if missing request_host and request_path", function()
       local valid, errors = validate_entity({
         name = "mockbin"
       }, api_schema)
-      assert.False(valid)
+      assert.is_false(valid)
       assert.equal("At least a 'request_host' or a 'request_path' must be specified", errors.request_path)
       assert.equal("At least a 'request_host' or a 'request_path' must be specified", errors.request_host)
 
@@ -300,7 +303,7 @@ describe("Entities Schemas", function()
         name = "mockbin",
         request_path = true
       }, api_schema)
-      assert.False(valid)
+      assert.is_false(valid)
       assert.equal("request_path is not a string", errors.request_path)
       assert.equal("At least a 'request_host' or a 'request_path' must be specified", errors.request_host)
     end)
@@ -310,7 +313,7 @@ describe("Entities Schemas", function()
 
       local valid, errors = validate_entity(t, api_schema)
       assert.falsy(errors)
-      assert.True(valid)
+      assert.is_true(valid)
       assert.equal("mockbin.com", t.name)
     end)
 
@@ -319,7 +322,7 @@ describe("Entities Schemas", function()
 
       local valid, errors = validate_entity(t, api_schema)
       assert.falsy(errors)
-      assert.True(valid)
+      assert.is_true(valid)
       assert.equal("mockbin", t.name)
     end)
 
@@ -327,14 +330,14 @@ describe("Entities Schemas", function()
       local t = {upstream_url = "http://mockbin.com", request_host = "mockbin.com"}
 
       local valid, errors = validate_entity(t, api_schema)
-      assert.True(valid)
+      assert.is_true(valid)
       assert.falsy(errors)
       assert.equal("mockbin.com", t.name)
 
       t = {upstream_url = "http://mockbin.com", request_path = "/mockbin/status"}
 
       valid, errors = validate_entity(t, api_schema)
-      assert.True(valid)
+      assert.is_true(valid)
       assert.falsy(errors)
       assert.equal("mockbin-status", t.name)
     end)
@@ -347,17 +350,17 @@ describe("Entities Schemas", function()
   describe("Consumers", function()
     it("should require a `custom_id` or `username`", function()
       local valid, errors = validate_entity({}, consumer_schema)
-      assert.False(valid)
+      assert.is_false(valid)
       assert.equal("At least a 'custom_id' or a 'username' must be specified", errors.username)
       assert.equal("At least a 'custom_id' or a 'username' must be specified", errors.custom_id)
 
       valid, errors = validate_entity({ username = "" }, consumer_schema)
-      assert.False(valid)
+      assert.is_false(valid)
       assert.equal("At least a 'custom_id' or a 'username' must be specified", errors.username)
       assert.equal("At least a 'custom_id' or a 'username' must be specified", errors.custom_id)
 
       valid, errors = validate_entity({ username = true }, consumer_schema)
-      assert.False(valid)
+      assert.is_false(valid)
       assert.equal("username is not a string", errors.username)
       assert.equal("At least a 'custom_id' or a 'username' must be specified", errors.custom_id)
     end)
@@ -377,20 +380,20 @@ describe("Entities Schemas", function()
 
     it("should not validate if the plugin doesn't exist (not installed)", function()
       local valid, errors = validate_entity({name = "world domination"}, plugins_schema)
-      assert.False(valid)
+      assert.is_false(valid)
       assert.equal("Plugin \"world domination\" not found", errors.config)
     end)
     it("should validate a plugin configuration's `config` field", function()
       -- Success
       local plugin = {name = "key-auth", api_id = "stub", config = {key_names = {"x-kong-key"}}}
       local valid = validate_entity(plugin, plugins_schema, {dao = dao_stub})
-      assert.True(valid)
+      assert.is_true(valid)
 
       -- Failure
       plugin = {name = "rate-limiting", api_id = "stub", config = { second = "hello" }}
 
       local valid, errors = validate_entity(plugin, plugins_schema, {dao = dao_stub})
-      assert.False(valid)
+      assert.is_false(valid)
       assert.equal("second is not a number", errors["config.second"])
     end)
     it("should have an empty config if none is specified and if the config schema does not have default", function()
@@ -398,7 +401,7 @@ describe("Entities Schemas", function()
       local plugin = {name = "key-auth", api_id = "stub"}
       local valid = validate_entity(plugin, plugins_schema, {dao = dao_stub})
       assert.same({key_names = {"apikey"}, hide_credentials = false, anonymous = false}, plugin.config)
-      assert.True(valid)
+      assert.is_true(valid)
     end)
     it("should be valid if no value is specified for a subfield and if the config schema has default as empty array", function()
       -- Insert response-transformer, whose default config has no default values, and should be empty
@@ -422,7 +425,7 @@ describe("Entities Schemas", function()
           json = {}
         }
       }, plugin2.config)
-      assert.True(valid)
+      assert.is_true(valid)
     end)
 
     describe("self_check", function()
@@ -439,16 +442,240 @@ describe("Entities Schemas", function()
         end
 
         local valid, _, err = validate_entity({name = "stub", api_id = "0000", consumer_id = "0000", config = {string = "foo"}}, plugins_schema)
-        assert.False(valid)
+        assert.is_false(valid)
         assert.equal("No consumer can be configured for that plugin", err.message)
 
         valid, err = validate_entity({name = "stub", api_id = "0000", config = {string = "foo"}}, plugins_schema, {dao = dao_stub})
-        assert.True(valid)
+        assert.is_true(valid)
         assert.falsy(err)
       end)
     end)
   end)
 
+  --
+  -- UPSTREAMS
+  --
+
+  describe("Upstreams", function()
+    local slots_default, slots_min, slots_max = 100, 10, 2^16
+
+    it("should require a valid `name` and no port", function()
+      local valid, errors, check
+      valid, errors = validate_entity({}, upstreams_schema)
+      assert.is_false(valid)
+      assert.equal("name is required", errors.name)
+
+      valid, errors, check = validate_entity({ name = "123.123.123.123" }, upstreams_schema)
+      assert.is_false(valid)
+      assert.is_nil(errors)
+      assert.equal("Invalid name; no ip addresses allowed", check.message)
+
+      valid, errors, check = validate_entity({ name = "\\\\bad\\\\////name////" }, upstreams_schema)
+      assert.is_false(valid)
+      assert.is_nil(errors)
+      assert.equal("Invalid name; must be a valid hostname", check.message)
+      
+      valid, errors, check = validate_entity({ name = "name:80" }, upstreams_schema)
+      assert.is_false(valid)
+      assert.is_nil(errors)
+      assert.equal("Invalid name; no port allowed", check.message)
+      
+      valid, errors, check = validate_entity({ name = "valid.host.name" }, upstreams_schema)
+      assert.is_true(valid)
+      assert.is_nil(errors)
+      assert.is_nil(check)
+    end)
+
+    it("should require (optional) slots in a valid range", function()
+      local valid, errors, check, _
+      local data = { name = "valid.host.name" }
+      valid, _, _ = validate_entity(data, upstreams_schema)
+      assert.is_true(valid)
+      assert.equal(slots_default, data.slots)
+
+      local bad_slots = { -1, slots_min - 1, slots_max + 1 }
+      for _, slots in ipairs(bad_slots) do
+        local data = { 
+          name = "valid.host.name",
+          slots = slots,
+        }
+        valid, errors, check = validate_entity(data, upstreams_schema)
+        assert.is_false(valid)
+        assert.is_nil(errors)
+        assert.equal("number of slots must be between "..slots_min.." and "..slots_max, check.message)
+      end
+      
+      local good_slots = { slots_min, 500, slots_max }
+      for _, slots in ipairs(good_slots) do
+        local data = { 
+          name = "valid.host.name",
+          slots = slots,
+        }
+        valid, errors, check = validate_entity(data, upstreams_schema)
+        assert.is_true(valid)
+        assert.is_nil(errors)
+        assert.is_nil(check)
+      end
+    end)
+  
+    it("should require (optional) orderlist to be a proper list", function()
+      local data, valid, errors, check
+      local function validate_order(list, size)
+        assert(type(list) == "table", "expected list table, got "..type(list))
+        assert(next(list), "table is empty")
+        assert(type(size) == "number", "expected size number, got "..type(size))
+        assert(size > 0, "expected size to be > 0")
+        local c = {}
+        local max = 0
+        for i,v in pairs(list) do  --> note: pairs, not ipairs!!
+          if i > max then max = i end
+          c[i] = v
+        end
+        assert(max == size, "highest key is not equal to the size")
+        table.sort(c)
+        max = 0
+        for i, v in ipairs(c) do
+          assert(i == v, "expected sorted table to have equal keys and values")
+          if i>max then max = i end
+        end
+        assert(max == size, "expected array, but got list with holes")
+      end
+    
+      for _ = 1, 20 do  -- have Kong generate 20 random sized arrays and verify them
+        data = { 
+          name = "valid.host.name",
+          slots = math.random(slots_min, slots_max)
+        }
+        valid, errors, check = validate_entity(data, upstreams_schema)
+        assert.is_true(valid)
+        assert.is_nil(errors)
+        assert.is_nil(check)
+        validate_order(data.orderlist, data.slots)
+      end
+
+      local lst = { 9,7,5,3,1,2,4,6,8,10 }   -- a valid list
+      data = { 
+        name = "valid.host.name",
+        slots = 10,
+        orderlist = utils.shallow_copy(lst)
+      }
+      valid, errors, check = validate_entity(data, upstreams_schema)
+      assert.is_true(valid)
+      assert.is_nil(errors)
+      assert.is_nil(check)
+      assert.same(lst, data.orderlist)
+    
+      data = { 
+        name = "valid.host.name",
+        slots = 10,
+        orderlist = { 9,7,5,3,1,2,4,6,8 }   -- too short (9)
+      }
+      valid, errors, check = validate_entity(data, upstreams_schema)
+      assert.is_false(valid)
+      assert.is_nil(errors)
+      assert.are.equal("size mismatch between 'slots' and 'orderlist'",check.message)
+
+      data = { 
+        name = "valid.host.name",
+        slots = 10,
+        orderlist = { 9,7,5,3,1,2,4,6,8,10,11 }   -- too long (11)
+      }
+      valid, errors, check = validate_entity(data, upstreams_schema)
+      assert.is_false(valid)
+      assert.is_nil(errors)
+      assert.are.equal("size mismatch between 'slots' and 'orderlist'",check.message)
+
+      data = { 
+        name = "valid.host.name",
+        slots = 10,
+        orderlist = { 9,7,5,3,1,2,4,6,8,8 }   -- a double value (2x 8, no 10)
+      }
+      valid, errors, check = validate_entity(data, upstreams_schema)
+      assert.is_false(valid)
+      assert.is_nil(errors)
+      assert.are.equal("invalid orderlist",check.message)
+
+      data = { 
+        name = "valid.host.name",
+        slots = 10,
+        orderlist = { 9,7,5,3,1,2,4,6,8,11 }   -- a hole (10 missing)
+      }
+      valid, errors, check = validate_entity(data, upstreams_schema)
+      assert.is_false(valid)
+      assert.is_nil(errors)
+      assert.are.equal("invalid orderlist",check.message)
+    end)
+
+  end)
+  
+  --
+  -- TARGETS
+  --
+
+  describe("Targets", function()
+    local weight_default, weight_min, weight_max = 100, 0, 1000
+    local default_port = 8000
+    
+    it("should validate the required 'target' field", function()
+      local valid, errors, check
+
+      valid, errors, check = validate_entity({}, targets_schema)
+      assert.is_false(valid)
+      assert.equal(errors.target, "target is required")
+      assert.is_nil(check)
+
+      local names = { "valid.name", "valid.name:8080", "12.34.56.78", "1.2.3.4:123" }
+      for _, name in ipairs(names) do
+        valid, errors, check = validate_entity({ target = name }, targets_schema)
+        assert.is_true(valid)
+        assert.is_nil(errors)
+        assert.is_nil(check)
+      end
+
+      valid, errors, check = validate_entity({ target = "\\\\bad\\\\////name////" }, targets_schema)
+      assert.is_false(valid)
+      assert.is_nil(errors)
+      assert.equal("Invalid target; not a valid hostname or ip address", check.message)
+
+    end)
+    
+    it("should normalize 'target' field and verify default port", function()
+      local valid, errors, check
+
+      -- the utils module does the normalization, here just check whether it is being invoked.
+      local names_in = { "012.034.056.078", "01.02.03.04:123" }
+      local names_out = { "12.34.56.78:"..default_port, "1.2.3.4:123" }
+      for i, name in ipairs(names_in) do
+        local data = { target = name }
+        valid, errors, check = validate_entity(data, targets_schema)
+        assert.is_true(valid)
+        assert.is_nil(errors)
+        assert.is_nil(check)
+        assert.equal(names_out[i], data.target)
+      end
+    end)
+  
+    it("should validate the optional 'weight' field", function()
+      local weights, valid, errors, check
+
+      weights = { -10, weight_min - 1, weight_max + 1 }
+      for _, weight in ipairs(weights) do
+        valid, errors, check = validate_entity({ target = "1.2.3.4", weight = weight }, targets_schema)
+        assert.is_false(valid)
+        assert.is_nil(errors)
+        assert.equal("weight must be from "..weight_min.." to "..weight_max, check.message)
+      end
+
+      weights = { weight_min, weight_default, weight_max }
+      for _, weight in ipairs(weights) do
+        valid, errors, check = validate_entity({ target = "1.2.3.4", weight = weight }, targets_schema)
+        assert.is_true(valid)
+        assert.is_nil(errors)
+        assert.is_nil(check)
+      end
+    end)
+  end)
+
   describe("update", function()
     it("should only validate updated fields", function()
       local t = {request_host = "", upstream_url = "http://mockbin.com"}
@@ -456,7 +683,7 @@ describe("Entities Schemas", function()
       local valid, errors = validate_entity(t, api_schema, {
         update = true
       })
-      assert.False(valid)
+      assert.is_false(valid)
       assert.same({
         request_host = "At least a 'request_host' or a 'request_path' must be specified"
       }, errors)
diff --git a/spec/01-unit/13-balancer_spec.lua b/spec/01-unit/13-balancer_spec.lua
new file mode 100644
index 000000000000..031f19d0f384
--- /dev/null
+++ b/spec/01-unit/13-balancer_spec.lua
@@ -0,0 +1,114 @@
+describe("Balancer", function()
+  local singletons, balancer
+  local UPSTREAMS_FIXTURES
+  local TARGETS_FIXTURES
+  --local uuid = require("kong.tools.utils").uuid
+
+  
+  setup(function()
+    balancer = require "kong.core.balancer"
+    singletons = require "kong.singletons"
+    singletons.dao = {}
+    singletons.dao.upstreams = {
+      find_all = function(self)
+        return UPSTREAMS_FIXTURES
+      end
+    }
+
+    UPSTREAMS_FIXTURES = {
+      {id = "a", name = "mashape", slots = 10, orderlist = {1,2,3,4,5,6,7,8,9,10} },
+      {id = "b", name = "kong",    slots = 10, orderlist = {10,9,8,7,6,5,4,3,2,1} },
+      {id = "c", name = "gelato",  slots = 20, orderlist = {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20} },
+      {id = "d", name = "galileo", slots = 20, orderlist = {20,19,18,17,16,15,14,13,12,11,10,9,8,7,6,5,4,3,2,1} },
+    }
+    
+    singletons.dao.targets = {
+      find_all = function(self, match_on)
+        local ret = {}
+        for _, rec in ipairs(TARGETS_FIXTURES) do
+          for key, val in pairs(match_on or {}) do
+            if rec[key] ~= val then
+              rec = nil
+              break
+            end
+          end
+          if rec then table.insert(ret, rec) end
+        end
+        return ret
+      end
+    }
+
+    TARGETS_FIXTURES = {
+      -- 1st upstream; a
+      {
+        id = "a1",
+        created_at = "003",
+        upstream_id = "a",
+        target = "mashape.com:80",
+        weight = 10,
+      },
+      {
+        id = "a2",
+        created_at = "002",
+        upstream_id = "a",
+        target = "mashape.com:80",
+        weight = 10,
+      },
+      {
+        id = "a3",
+        created_at = "001",
+        upstream_id = "a",
+        target = "mashape.com:80",
+        weight = 10,
+      },
+      {
+        id = "a4",
+        created_at = "002",  -- same timestamp as "a2"
+        upstream_id = "a",
+        target = "mashape.com:80",
+        weight = 10,
+      },
+      -- 2nd upstream; b
+      {
+        id = "b1",
+        created_at = "003",
+        upstream_id = "b",
+        target = "mashape.com:80",
+        weight = 10,
+      },
+    }
+  end)
+
+  describe("load_upstreams_dict_into_memory()", function()
+    local upstreams_dict
+    setup(function()
+      upstreams_dict = balancer._load_upstreams_dict_into_memory()
+    end)
+
+    it("retrieves all upstreams as a dictionary", function()
+      assert.is.table(upstreams_dict)
+      for _, u in ipairs(UPSTREAMS_FIXTURES) do
+        assert.equal(upstreams_dict[u.name], u.id)
+        upstreams_dict[u.name] = nil -- remove each match
+      end
+      assert.is_nil(next(upstreams_dict)) -- should be empty now
+    end)
+  end)
+
+  describe("load_targets_into_memory()", function()
+    local targets
+    local upstream
+    setup(function()
+      upstream = "a"
+      targets = balancer._load_targets_into_memory(upstream)
+    end)
+
+    it("retrieves all targets per upstream, ordered", function()
+      assert.equal(4, #targets)
+      assert(targets[1].id == "a3")
+      assert(targets[2].id == "a2")
+      assert(targets[3].id == "a4")
+      assert(targets[4].id == "a1")
+    end)
+  end)
+end)
diff --git a/spec/02-integration/03-admin_api/07-upstreams_routes_spec.lua b/spec/02-integration/03-admin_api/07-upstreams_routes_spec.lua
new file mode 100644
index 000000000000..9448ef53aba9
--- /dev/null
+++ b/spec/02-integration/03-admin_api/07-upstreams_routes_spec.lua
@@ -0,0 +1,473 @@
+local helpers = require "spec.helpers"
+
+local slots_default, slots_max = 100, 2^16
+
+local function it_content_types(title, fn)
+  local test_form_encoded = fn("application/x-www-form-urlencoded")
+  local test_json = fn("application/json")
+  it(title.." with application/www-form-urlencoded", test_form_encoded)
+  it(title.." with application/json", test_json)
+end
+
+local function validate_order(list, size)
+  assert(type(list) == "table", "expected list table, got "..type(list))
+  assert(next(list), "table is empty")
+  assert(type(size) == "number", "expected size number, got "..type(size))
+  assert(size > 0, "expected size to be > 0")
+  local c = {}
+  local max = 0
+  for i,v in pairs(list) do  --> note: pairs, not ipairs!!
+    if i > max then max = i end
+    c[i] = v
+  end
+  assert(max == size, "highest key is not equal to the size")
+  table.sort(c)
+  max = 0
+  for i, v in ipairs(c) do
+    assert(i == v, "expected sorted table to have equal keys and values")
+    if i>max then max = i end
+  end
+  assert(max == size, "expected array, but got list with holes")
+end
+
+describe("Admin API", function()
+  local client
+  setup(function()
+    assert(helpers.start_kong())
+    client = assert(helpers.admin_client())
+  end)
+  teardown(function()
+    if client then client:close() end
+    helpers.stop_kong()
+  end)
+
+  describe("/upstreams", function()
+    describe("POST", function()
+      before_each(function()
+        helpers.dao:truncate_tables()
+      end)
+      it_content_types("creates an upstream with defaults", function(content_type)
+        return function()
+          local res = assert(client:send {
+            method = "POST",
+            path = "/upstreams",
+            body = {
+              name = "my.upstream",
+            },
+            headers = {["Content-Type"] = content_type}
+          })
+          assert.response(res).has.status(201)
+          local json = assert.response(res).has.jsonbody()
+          assert.equal("my.upstream", json.name)
+          assert.is_number(json.created_at)
+          assert.is_string(json.id)
+          assert.are.equal(slots_default, json.slots)
+          validate_order(json.orderlist, json.slots)
+        end
+      end)
+      it("creates an upstream without defaults with application/json", function()
+        local res = assert(client:send {
+          method = "POST",
+          path = "/upstreams",
+          body = {
+            name = "my.upstream",
+            slots = 10,
+            orderlist = { 10,9,8,7,6,5,4,3,2,1 },
+          },
+          headers = {["Content-Type"] = "application/json"}
+        })
+        assert.response(res).has.status(201)
+        local json = assert.response(res).has.jsonbody()
+        assert.equal("my.upstream", json.name)
+        assert.is_number(json.created_at)
+        assert.is_string(json.id)
+        assert.are.equal(10, json.slots)
+        validate_order(json.orderlist, json.slots)
+        assert.are.same({ 10,9,8,7,6,5,4,3,2,1 }, json.orderlist)
+      end)
+      pending("creates an upstream without defaults with application/www-form-urlencoded", function()
+-- pending due to inability to pass array
+-- see also the todo's below
+        local res = assert(client:send {
+          method = "POST",
+          path = "/upstreams",
+          body = "name=my.upstream&slots=10&"..
+                 "orderlist[]=10&orderlist[]=9&orderlist[]=8&orderlist[]=7&"..
+                 "orderlist[]=6&orderlist[]=5&orderlist[]=4&orderlist[]=3&"..
+                 "orderlist[]=2&orderlist[]=1",
+          headers = {["Content-Type"] = "application/www-form-urlencoded"}
+        })
+        assert.response(res).has.status(201)
+        local json = assert.response(res).has.jsonbody()
+        assert.equal("my.upstream", json.name)
+        assert.is_number(json.created_at)
+        assert.is_string(json.id)
+        assert.are.equal(10, json.slots)
+        validate_order(json.orderlist, json.slots)
+        assert.are.same({ 10,9,8,7,6,5,4,3,2,1 }, json.orderlist)
+      end)
+      it("creates an upstream with "..slots_max.." slots", function(content_type)
+        local res = assert(client:send {
+          method = "POST",
+          path = "/upstreams",
+          body = {
+            name = "my.upstream",
+            slots = slots_max,
+          },
+          headers = {["Content-Type"] = "application/json"}
+        })
+        assert.response(res).has.status(201)
+        local json = assert.response(res).has.jsonbody()
+        assert.equal("my.upstream", json.name)
+        assert.is_number(json.created_at)
+        assert.is_string(json.id)
+        assert.are.equal(slots_max, json.slots)
+        validate_order(json.orderlist, json.slots)
+      end)
+      describe("errors", function()
+        it("handles malformed JSON body", function()
+          local res = assert(client:request {
+            method = "POST",
+            path = "/upstreams",
+            body = '{"hello": "world"',
+            headers = {["Content-Type"] = "application/json"}
+          })
+          local body = assert.res_status(400, res)
+          assert.equal('{"message":"Cannot parse JSON body"}', body)
+        end)
+        it_content_types("handles invalid input", function(content_type)
+          return function()
+            -- Missing parameter
+            local res = assert(client:send {
+              method = "POST",
+              path = "/upstreams",
+              body = {
+                slots = 50,
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            local body = assert.res_status(400, res)
+            assert.equal([[{"name":"name is required"}]], body)
+
+            -- Invalid name parameter
+            res = assert(client:send {
+              method = "POST",
+              path = "/upstreams",
+              body = {
+                name = "some invalid host name",
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            body = assert.res_status(400, res)
+            assert.equal([[{"message":"Invalid name; must be a valid hostname"}]], body)
+            -- Invalid slots parameter
+            res = assert(client:send {
+              method = "POST",
+              path = "/upstreams",
+              body = {
+                name = "my.upstream",
+                slots = 2^16+1
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            body = assert.res_status(400, res)
+            assert.equal([[{"message":"number of slots must be between 10 and 65536"}]], body)
+          end
+        end)
+        it_content_types("handles invalid input - orderlist", function(content_type)
+          return function()
+--TODO: line below disables the test for urlencoded, because the orderlist array isn't passed/received properly
+if content_type == "application/x-www-form-urlencoded" then return end
+            -- non-integers
+            local res = assert(client:send {
+              method = "POST",
+              path = "/upstreams",
+              body = {
+                name = "my.upstream",
+                slots = 10,
+                orderlist = { "one","two","three","four","five","six","seven","eight","nine","ten" },
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            local body = assert.res_status(400, res)
+            assert.equal([[{"message":"invalid orderlist"}]], body)
+            -- non-consecutive
+            res = assert(client:send {
+              method = "POST",
+              path = "/upstreams",
+              body = {
+                name = "my.upstream",
+                slots = 10,
+                orderlist = { 1,2,3,4,5,6,7,8,9,11 }, -- 10 is missing
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            body = assert.res_status(400, res)
+            assert.equal([[{"message":"invalid orderlist"}]], body)
+            -- doubles
+            res = assert(client:send {
+              method = "POST",
+              path = "/upstreams",
+              body = {
+                name = "my.upstream",
+                slots = 10,
+                orderlist = { 1,2,3,4,5,1,2,3,4,5 }, 
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            body = assert.res_status(400, res)
+            assert.equal([[{"message":"invalid orderlist"}]], body)
+          end
+        end)
+        it_content_types("returns 409 on conflict", function(content_type)
+          return function()
+            local res = assert(client:send {
+              method = "POST",
+              path = "/upstreams",
+              body = {
+                name = "my.upstream",
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            assert.res_status(201, res)
+
+            res = assert(client:send {
+              method = "POST",
+              path = "/upstreams",
+              body = {
+                name = "my.upstream",
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            local body = assert.res_status(409, res)
+            assert.equal([[{"name":"already exists with value 'my.upstream'"}]], body)
+          end
+        end)
+      end)
+    end)
+
+    describe("PUT", function()
+      before_each(function()
+        helpers.dao:truncate_tables()
+      end)
+
+      it_content_types("creates if not exists", function(content_type)
+        return function()
+          local res = assert(client:send {
+            method = "PUT",
+            path = "/upstreams",
+            body = {
+              name = "my-upstream",
+              created_at = 1461276890000
+            },
+            headers = {["Content-Type"] = content_type}
+          })
+          assert.response(res).has.status(201)
+          local json = assert.response(res).has.jsonbody()
+          assert.equal("my-upstream", json.name)
+          assert.is_number(json.created_at)
+          assert.is_string(json.id)
+          assert.is_number(json.slots)
+          assert.is_table(json.orderlist)
+        end
+      end)
+      --it_content_types("replaces if exists", function(content_type)
+      pending("replaces if exists", function(content_type)
+--TODO: no idea why this fails in an odd manner...
+        return function()
+          local res = assert(client:send {
+            method = "POST",
+            path = "/upstreams",
+            body = {
+              name = "my-upstream",
+              slots = 100,
+            },
+            headers = {["Content-Type"] = content_type}
+          })
+          assert.response(res).has.status(201)
+          local json = assert.response(res).has.jsonbody()
+
+          res = assert(client:send {
+            method = "PUT",
+            path = "/upstreams",
+            body = {
+              id = json.id,
+              name = "my-new-upstream",
+              slots = 123,
+              created_at = json.created_at
+            },
+            headers = {["Content-Type"] = content_type}
+          })
+          assert.response(res).has.status(200)
+          local updated_json = assert.response(res).has.jsonbody()
+          assert.equal("my-new-upstream", updated_json.name)
+          assert.equal(123, updated_json.slots)
+          assert.equal(json.id, updated_json.id)
+          assert.equal(json.created_at, updated_json.created_at)
+        end
+      end)
+      describe("errors", function()
+        it_content_types("handles invalid input", function(content_type)
+          return function()
+            -- Missing parameter
+            local res = assert(client:send {
+              method = "PUT",
+              path = "/upstreams",
+              body = {},
+              headers = {["Content-Type"] = content_type}
+            })
+            local body = assert.response(res).has.status(400)
+            assert.equal([[{"name":"name is required"}]], body)
+
+            -- Invalid parameter
+            res = assert(client:send {
+              method = "PUT",
+              path = "/upstreams",
+              body = {
+                name = "1.2.3.4", -- ip is not allowed
+                created_at = 1461276890000
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            body = assert.response(res).has.status(400)
+            assert.equal([[{"message":"Invalid name; no ip addresses allowed"}]], body)
+          end
+        end)
+        it_content_types("returns 409 on conflict", function(content_type)
+          return function()
+            -- @TODO this particular test actually defeats the purpose of PUT.
+            -- It should probably replace the entity
+            local res = assert(client:send {
+                method = "PUT",
+                path = "/upstreams",
+                body = {
+                  name = "my-upstream",
+                  created_at = 1461276890000
+                },
+                headers = {["Content-Type"] = content_type}
+              })
+              assert.response(res).has.status(201)
+              local json = assert.response(res).has.jsonbody()
+
+              res = assert(client:send {
+                method = "PUT",
+                path = "/upstreams",
+                body = {
+                  name = "my-upstream",
+                  created_at = json.created_at
+                },
+                headers = {["Content-Type"] = content_type}
+              })
+              local body = assert.response(res).has.status(409)
+              assert.equal([[{"name":"already exists with value 'my-upstream'"}]], body)
+            end
+        end)
+      end)
+    end)
+
+    describe("GET", function()
+      setup(function()
+        helpers.dao:truncate_tables()
+
+        for i = 1, 10 do
+          assert(helpers.dao.upstreams:insert {
+            name = "upstream-"..i,
+          })
+        end
+      end)
+      teardown(function()
+        helpers.dao:truncate_tables()
+      end)
+
+      it("retrieves the first page", function()
+        local res = assert(client:send {
+          methd = "GET",
+          path = "/upstreams"
+        })
+        assert.response(res).has.status(200)
+        local json = assert.response(res).has.jsonbody()
+        assert.equal(10, #json.data)
+        assert.equal(10, json.total)
+      end)
+      it("paginates a set", function()
+        local pages = {}
+        local offset
+
+        for i = 1, 4 do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/upstreams",
+            query = {size = 3, offset = offset}
+          })
+          assert.response(res).has.status(200)
+          local json = assert.response(res).has.jsonbody()
+          assert.equal(10, json.total)
+
+          if i < 4 then
+            assert.equal(3, #json.data)
+          else
+            assert.equal(1, #json.data)
+          end
+
+          if i > 1 then
+            -- check all pages are different
+            assert.not_same(pages[i-1], json)
+          end
+
+          offset = json.offset
+          pages[i] = json
+        end
+      end)
+      it("handles invalid filters", function()
+          local res = assert(client:send {
+            method = "GET",
+            path = "/upstreams",
+            query = {foo = "bar"}
+          })
+          local body = assert.res_status(400, res)
+          assert.equal([[{"foo":"unknown field"}]], body)
+      end)
+      it("ignores an invalid body", function()
+        local res = assert(client:send {
+          methd = "GET",
+          path = "/upstreams",
+          body = "this fails if decoded as json",
+          headers = {
+            ["Content-Type"] = "application/json",
+          }
+        })
+        assert.res_status(200, res)
+      end)
+
+      describe("empty results", function()
+        setup(function()
+          helpers.dao:truncate_tables()
+        end)
+
+        it("data property is an empty array", function()
+          local res = assert(client:send {
+            method = "GET",
+            path = "/upstreams"
+          })
+          local body = assert.res_status(200, res)
+          assert.equal([[{"data":[],"total":0}]], body)
+        end)
+      end)
+    end)
+
+    it("returns 405 on invalid method", function()
+      local methods = {"DELETE"}
+      for i = 1, #methods do
+        local res = assert(client:send {
+          method = methods[i],
+          path = "/apis",
+          body = {}, -- tmp: body to allow POST/PUT to work
+          headers = {["Content-Type"] = "application/json"}
+        })
+        local body = assert.response(res).has.status(405)
+        assert.equal([[{"message":"Method not allowed"}]], body)
+      end
+    end)
+
+  end)
+end)
diff --git a/spec/02-integration/03-admin_api/08-targets_routes_spec.lua b/spec/02-integration/03-admin_api/08-targets_routes_spec.lua
new file mode 100644
index 000000000000..cfd5b16d0dd0
--- /dev/null
+++ b/spec/02-integration/03-admin_api/08-targets_routes_spec.lua
@@ -0,0 +1,262 @@
+local helpers = require "spec.helpers"
+--local cjson = require "cjson"
+
+local function it_content_types(title, fn)
+  local test_form_encoded = fn("application/x-www-form-urlencoded")
+  local test_json = fn("application/json")
+  it(title.." with application/www-form-urlencoded", test_form_encoded)
+  it(title.." with application/json", test_json)
+end
+
+local upstream_name = "my_upstream"
+
+describe("Admin API", function()
+  
+  local client, upstream
+  local weight_default, weight_min, weight_max = 100, 0, 1000
+  local default_port = 8000
+  
+  before_each(function()
+    assert(helpers.start_kong())
+    client = assert(helpers.admin_client())
+    
+    upstream = assert(helpers.dao.upstreams:insert {
+      name = upstream_name,
+      slots = 10,
+      orderlist = { 1,2,3,4,5,6,7,8,9,10 }
+    })
+  end)
+  
+  after_each(function()
+    if client then client:close() end
+    helpers.stop_kong()
+  end)
+
+  describe("/upstreams/{upstream}/targets/", function()
+    describe("POST", function()
+      it_content_types("creates a target with defaults", function(content_type)
+        return function()
+          local res = assert(client:send {
+            method = "POST",
+            path = "/upstreams/"..upstream_name.."/targets/",
+            body = {
+              target = "mashape.com",
+            },
+            headers = {["Content-Type"] = content_type}
+          })
+          assert.response(res).has.status(201)
+          local json = assert.response(res).has.jsonbody()
+          assert.equal("mashape.com:"..default_port, json.target)
+          assert.is_number(json.created_at)
+          assert.is_string(json.id)
+          assert.are.equal(weight_default, json.weight)
+        end
+      end)
+      it_content_types("creates a target without defaults", function(content_type)
+        return function()
+          local res = assert(client:send {
+            method = "POST",
+            path = "/upstreams/"..upstream_name.."/targets/",
+            body = {
+              target = "mashape.com:123",
+              weight = 99,
+            },
+            headers = {["Content-Type"] = content_type}
+          })
+          assert.response(res).has.status(201)
+          local json = assert.response(res).has.jsonbody()
+          assert.equal("mashape.com:123", json.target)
+          assert.is_number(json.created_at)
+          assert.is_string(json.id)
+          assert.are.equal(99, json.weight)
+        end
+      end)
+      it("cleans up old target entries", function()
+        -- count to 12; 10 old ones, 1 active one, and then nr 12 to
+        -- trigger the cleanup
+        for i = 1, 12 do
+          local res = assert(client:send {
+            method = "POST",
+            path = "/upstreams/"..upstream_name.."/targets/",
+            body = {
+              target = "mashape.com:123",
+              weight = 99,
+            },
+            headers = {
+              ["Content-Type"] = "application/json"
+            },
+          })
+          assert.response(res).has.status(201)
+        end
+        local history = assert(helpers.dao.targets:find_all {
+          upstream_id = upstream.id,
+        })
+        -- there should be 2 left; 1 from the cleanup, and the final one 
+        -- inserted that triggered the cleanup
+        assert.equal(2, #history)
+      end)
+      
+      describe("errors", function()
+        it("handles malformed JSON body", function()
+          local res = assert(client:request {
+            method = "POST",
+            path = "/upstreams/"..upstream_name.."/targets/",
+            body = '{"hello": "world"',
+            headers = {["Content-Type"] = "application/json"}
+          })
+          local body = assert.response(res).has.status(400)
+          assert.equal('{"message":"Cannot parse JSON body"}', body)
+        end)
+        it_content_types("handles invalid input", function(content_type)
+          return function()
+            -- Missing parameter
+            local res = assert(client:send {
+              method = "POST",
+              path = "/upstreams/"..upstream_name.."/targets/",
+              body = {
+                weight = weight_min,
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            local body = assert.response(res).has.status(400)
+            assert.equal([[{"target":"target is required"}]], body)
+
+            -- Invalid target parameter
+            res = assert(client:send {
+              method = "POST",
+              path = "/upstreams/"..upstream_name.."/targets/",
+              body = {
+                target = "some invalid host name",
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            body = assert.response(res).has.status(400)
+            assert.equal([[{"message":"Invalid target; not a valid hostname or ip address"}]], body)
+            
+            -- Invalid weight parameter
+            res = assert(client:send {
+              method = "POST",
+              path = "/upstreams/"..upstream_name.."/targets/",
+              body = {
+                target = "mashape.com",
+                weight = weight_max + 1,
+              },
+              headers = {["Content-Type"] = content_type}
+            })
+            body = assert.response(res).has.status(400)
+            assert.equal([[{"message":"weight must be from 0 to 1000"}]], body)
+          end
+        end)
+        
+        for _, method in ipairs({"PUT", "PATCH", "DELETE"}) do
+          it_content_types("returns 405 on "..method, function(content_type)
+            return function()
+              local res = assert(client:send {
+                method = method,
+                path = "/upstreams/"..upstream_name.."/targets/",
+                body = {
+                  target = "mashape.com",
+                },
+                headers = {["Content-Type"] = content_type}
+              })
+              assert.response(res).has.status(405)
+            end
+          end)
+        end
+      end)
+    end)
+
+    describe("GET", function()
+      before_each(function()
+        for i = 1, 10 do
+          assert(helpers.dao.targets:insert {
+            target = "api-"..i..":80",
+            weight = 100,
+            upstream_id = upstream.id,
+          })
+        end
+      end)
+    
+      it("retrieves the first page", function()
+        local res = assert(client:send {
+          methd = "GET",
+          path = "/upstreams/"..upstream_name.."/targets/",
+        })
+        assert.response(res).has.status(200)
+        local json = assert.response(res).has.jsonbody()
+        assert.equal(10, #json.data)
+        assert.equal(10, json.total)
+      end)
+      it("paginates a set", function()
+        local pages = {}
+        local offset
+
+        for i = 1, 4 do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/upstreams/"..upstream_name.."/targets/",
+            query = {size = 3, offset = offset}
+          })
+          assert.response(res).has.status(200)
+          local json = assert.response(res).has.jsonbody()
+          assert.equal(10, json.total)
+
+          if i < 4 then
+            assert.equal(3, #json.data)
+          else
+            assert.equal(1, #json.data)
+          end
+
+          if i > 1 then
+            -- check all pages are different
+            assert.not_same(pages[i-1], json)
+          end
+
+          offset = json.offset
+          pages[i] = json
+        end
+      end)
+      it("handles invalid filters", function()
+        local res = assert(client:send {
+          method = "GET",
+          path = "/upstreams/"..upstream_name.."/targets/",
+          query = {foo = "bar"},
+        })
+        local body = assert.response(res).has.status(400)
+        assert.equal([[{"foo":"unknown field"}]], body)
+      end)
+      it("ignores an invalid body", function()
+        local res = assert(client:send {
+          methd = "GET",
+          path = "/upstreams/"..upstream_name.."/targets/",
+          body = "this fails if decoded as json",
+          headers = {
+            ["Content-Type"] = "application/json",
+          }
+        })
+        assert.response(res).has.status(200)
+      end)
+
+      describe("empty results", function()
+        local upstream_name2 = "getkong.org"
+        
+        before_each(function()
+          assert(helpers.dao.upstreams:insert {
+            name = upstream_name2,
+            slots = 10,
+            orderlist = { 1,2,3,4,5,6,7,8,9,10 }
+          })
+        end)
+        
+        it("data property is an empty array", function()
+          local res = assert(client:send {
+            method = "GET",
+            path = "/upstreams/"..upstream_name2.."/targets/",
+          })
+          local body = assert.response(res).has.status(200)
+          assert.equal([[{"data":[],"total":0}]], body)
+        end)
+      end)
+    end)
+  end)
+end)
diff --git a/spec/02-integration/04-core/02-hooks_spec.lua b/spec/02-integration/04-core/02-hooks_spec.lua
index ec8b52b913e8..e05b97d5f17c 100644
--- a/spec/02-integration/04-core/02-hooks_spec.lua
+++ b/spec/02-integration/04-core/02-hooks_spec.lua
@@ -7,10 +7,22 @@ local pl_path = require "pl.path"
 local pl_file = require "pl.file"
 local pl_stringx = require "pl.stringx"
 
+local api_client
+
+local function get_cache(key)
+  local r = assert(api_client:send {
+    method = "GET",
+    path = "/cache/"..key,
+    headers = {}
+  })
+  assert.response(r).has.status(200)
+  return assert.response(r).has.jsonbody()
+end
+
 describe("Core Hooks", function()
   describe("Global", function()
     describe("Global Plugin entity invalidation on API", function()
-      local client, api_client
+      local client
       local plugin
 
       before_each(function()
@@ -49,11 +61,7 @@ describe("Core Hooks", function()
         assert.is_string(res.headers["X-RateLimit-Limit-minute"])
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.plugin_key("rate-limiting", nil, nil)
-        })
-        assert.res_status(200, res)
+        get_cache(cache.plugin_key("rate-limiting", nil, nil))
 
         -- Delete plugin
         local res = assert(api_client:send {
@@ -63,14 +71,7 @@ describe("Core Hooks", function()
         assert.res_status(204, res)
 
         -- Wait for cache to be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.plugin_key("rate-limiting", nil, nil)
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.plugin_key("rate-limiting", nil, nil))
 
         -- Consuming the API again without any authorization
         local res = assert(client:send {
@@ -86,7 +87,7 @@ describe("Core Hooks", function()
     end)
 
     describe("Global Plugin entity invalidation on Consumer", function()
-      local client, api_client
+      local client
       local plugin, consumer
 
       setup(function()
@@ -142,11 +143,7 @@ describe("Core Hooks", function()
         assert.is_string(res.headers["X-RateLimit-Limit-minute"])
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.plugin_key("rate-limiting", nil, consumer.id)
-        })
-        assert.res_status(200, res)
+        get_cache(cache.plugin_key("rate-limiting", nil, consumer.id))
 
         -- Delete plugin
         local res = assert(api_client:send {
@@ -156,14 +153,7 @@ describe("Core Hooks", function()
         assert.res_status(204, res)
 
         -- Wait for cache to be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.plugin_key("rate-limiting", nil, consumer.id)
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.plugin_key("rate-limiting", nil, consumer.id))
 
         -- Consuming the API again without any authorization
         local res = assert(client:send {
@@ -203,7 +193,7 @@ describe("Core Hooks", function()
   end)
 
   describe("Other", function()
-    local client, api_client
+    local client
     local consumer, api1, api2, basic_auth2, api3, rate_limiting_consumer
 
     before_each(function()
@@ -282,11 +272,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.plugin_key("basic-auth", api2.id, nil)
-        })
-        assert.res_status(200, res)
+        get_cache(cache.plugin_key("basic-auth", api2.id, nil))
 
         -- Delete plugin
         local res = assert(api_client:send {
@@ -296,14 +282,7 @@ describe("Core Hooks", function()
         assert.res_status(204, res)
 
         -- Wait for cache to be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.plugin_key("basic-auth", api2.id, nil)
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.plugin_key("basic-auth", api2.id, nil))
 
         -- Consuming the API again without any authorization
         local res = assert(client:send {
@@ -339,11 +318,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.plugin_key("basic-auth", api2.id, nil)
-        })
-        assert.res_status(200, res)
+        get_cache(cache.plugin_key("basic-auth", api2.id, nil))
 
         -- Update plugin
         local res = assert(api_client:send {
@@ -359,14 +334,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Wait for cache to be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.plugin_key("basic-auth", api2.id, nil)
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.plugin_key("basic-auth", api2.id, nil))
 
         -- Consuming the API again without any authorization
         local res = assert(client:send {
@@ -393,11 +361,7 @@ describe("Core Hooks", function()
         assert.equal(3, tonumber(res.headers["x-ratelimit-limit-minute"]))
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.plugin_key("rate-limiting", api3.id, consumer.id)
-        })
-        assert.res_status(200, res)
+        get_cache(cache.plugin_key("rate-limiting", api3.id, consumer.id))
 
         -- Delete plugin
         local res = assert(api_client:send {
@@ -407,14 +371,7 @@ describe("Core Hooks", function()
         assert.res_status(204, res)
 
         -- Wait for cache to be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.plugin_key("rate-limiting", api3.id, consumer.id)
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.plugin_key("rate-limiting", api3.id, consumer.id))
 
         -- Consuming the API again
         local res = assert(client:send {
@@ -443,11 +400,7 @@ describe("Core Hooks", function()
         assert.equal(3, tonumber(res.headers["x-ratelimit-limit-minute"]))
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.plugin_key("rate-limiting", api3.id, consumer.id)
-        })
-        assert.res_status(200, res)
+        get_cache(cache.plugin_key("rate-limiting", api3.id, consumer.id))
 
         -- Update plugin
         local res = assert(api_client:send {
@@ -463,14 +416,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Wait for cache to be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.plugin_key("rate-limiting", api3.id, consumer.id)
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.plugin_key("rate-limiting", api3.id, consumer.id))
 
         -- Consuming the API again
         local res = assert(client:send {
@@ -484,6 +430,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
         assert.equal(10, tonumber(res.headers["x-ratelimit-limit-minute"]))
       end)
+
     end)
 
     describe("Consumer entity invalidation", function()
@@ -500,11 +447,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.consumer_key(consumer.id)
-        })
-        assert.res_status(200, res)
+        get_cache(cache.consumer_key(consumer.id))
 
         -- Delete consumer
         local res = assert(api_client:send {
@@ -514,24 +457,10 @@ describe("Core Hooks", function()
         assert.res_status(204, res)
 
         -- Wait for consumer be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.consumer_key(consumer.id)
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.consumer_key(consumer.id))
 
         -- Wait for Basic Auth credential to be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.basicauth_credential_key("user123")
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.basicauth_credential_key("user123"))
 
         -- Consuming the API again
         local res = assert(client:send {
@@ -558,11 +487,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.consumer_key(consumer.id)
-        })
-        assert.res_status(200, res)
+        get_cache(cache.consumer_key(consumer.id))
 
         -- Update consumer
         local res = assert(api_client:send {
@@ -578,14 +503,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Wait for consumer be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.consumer_key(consumer.id)
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.consumer_key(consumer.id),3)
 
         -- Consuming the API again
         local res = assert(client:send {
@@ -599,12 +517,8 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Making sure the cache is updated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.consumer_key(consumer.id)
-        })
-        local body = assert.res_status(200, res)
-        assert.equal("updated_consumer", cjson.decode(body).username)
+        local body = get_cache(cache.consumer_key(consumer.id))
+        assert.equal("updated_consumer", body.username)
       end)
     end)
 
@@ -621,11 +535,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.all_apis_by_dict_key()
-        })
-        assert.res_status(200, res)
+        get_cache(cache.all_apis_by_dict_key())
 
         -- Adding a new API
         local res = assert(api_client:send {
@@ -642,15 +552,7 @@ describe("Core Hooks", function()
         assert.res_status(201, res)
 
         -- Wait for consumer be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.all_apis_by_dict_key(),
-            headers = {}
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.all_apis_by_dict_key())
 
         -- Consuming the API again
         local res = assert(client:send {
@@ -663,11 +565,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.all_apis_by_dict_key()
-        })
-        local body = cjson.decode(assert.res_status(200, res))
+        local body = get_cache(cache.all_apis_by_dict_key())
         assert.is_table(body.by_dns["hooks1.com"])
         assert.is_table(body.by_dns["dynamic-hooks.com"])
       end)
@@ -684,11 +582,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.all_apis_by_dict_key()
-        })
-        local body = cjson.decode(assert.res_status(200, res))
+        local body = get_cache(cache.all_apis_by_dict_key())
         assert.equal("http://mockbin.com", body.by_dns["hooks1.com"].upstream_url)
 
         -- Update API
@@ -705,15 +599,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Wait for consumer be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.all_apis_by_dict_key(),
-            headers = {}
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.all_apis_by_dict_key())
 
         -- Consuming the API again
         local res = assert(client:send {
@@ -726,12 +612,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Make sure the cache is populated with updated value
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.all_apis_by_dict_key(),
-          headers = {}
-        })
-        local body = cjson.decode(assert.res_status(200, res))
+        local body = get_cache(cache.all_apis_by_dict_key())
         assert.equal("http://mockbin.org", body.by_dns["hooks1.com"].upstream_url)
         assert.equal(3, pl_tablex.size(body.by_dns))
       end)
@@ -748,11 +629,7 @@ describe("Core Hooks", function()
         assert.res_status(200, res)
 
         -- Make sure the cache is populated
-        local res = assert(api_client:send {
-          method = "GET",
-          path = "/cache/"..cache.all_apis_by_dict_key()
-        })
-        local body = cjson.decode(assert.res_status(200, res))
+        local body = get_cache(cache.all_apis_by_dict_key())
         assert.equal("http://mockbin.com", body.by_dns["hooks1.com"].upstream_url)
 
         -- Deleting the API
@@ -763,15 +640,7 @@ describe("Core Hooks", function()
         assert.res_status(204, res)
 
         -- Wait for consumer be invalidated
-        helpers.wait_until(function()
-          local res = assert(api_client:send {
-            method = "GET",
-            path = "/cache/"..cache.all_apis_by_dict_key(),
-            headers = {}
-          })
-          res:read_body()
-          return res.status == 404
-        end, 3)
+        helpers.wait_for_invalidation(cache.all_apis_by_dict_key())
 
         -- Consuming the API again
         local res = assert(client:send {
@@ -784,15 +653,264 @@ describe("Core Hooks", function()
         assert.res_status(404, res)
 
         -- Make sure the cache is populated with zero APIs
+        local body = get_cache(cache.all_apis_by_dict_key())
+        assert.equal(2, pl_tablex.size(body.by_dns))
+      end)
+    end)
+
+    describe("Upstreams entity", function()
+      local upstream
+      
+      before_each(function()
+        assert(helpers.dao.apis:insert {
+          request_host = "hooks2.com",
+          upstream_url = "http://mybalancer"
+        })
+        upstream = assert(helpers.dao.upstreams:insert {
+          name = "mybalancer",
+        })
+        assert(helpers.dao.targets:insert {
+          upstream_id = upstream.id,
+          target = "mockbin.com:80",
+          weight = 10,
+        })
+      end)
+      it("invalidates the upstream-list when adding an upstream", function()
+        -- Making a request to populate the cache with the upstreams
+        local res = assert(client:send {
+          method = "GET",
+          path = "/status/200",
+          headers = {
+            ["Host"] = "hooks2.com"
+          }
+        })
+        assert.response(res).has.status(200)
+        -- validate that the cache is populated
+        get_cache(cache.upstreams_dict_key(upstream.id))
+        -- add an upstream
         local res = assert(api_client:send {
+          method = "POST",
+          path = "/upstreams",
+          headers = {
+            ["Content-Type"] = "application/json"
+          },
+          body = {
+            name = "my2nd.upstream",
+          },
+        })
+        assert.response(res).has.status(201)
+        -- wait for invalidation of the cache
+        helpers.wait_for_invalidation(cache.upstreams_dict_key(upstream.id))
+      end)
+      it("invalidates the upstream-list when updating an upstream", function()
+        -- Making a request to populate the cache with the upstreams
+        local res = assert(client:send {
           method = "GET",
-          path = "/cache/"..cache.all_apis_by_dict_key()
+          path = "/status/200",
+          headers = {
+            ["Host"] = "hooks2.com"
+          }
         })
-        local body = cjson.decode(assert.res_status(200, res))
-        assert.equal(2, pl_tablex.size(body.by_dns))
+        assert.response(res).has.status(200)
+        -- validate that the cache is populated
+        get_cache(cache.upstreams_dict_key(upstream.id))
+        -- patch the upstream
+        local res = assert(api_client:send {
+          method = "PATCH",
+          path = "/upstreams/"..upstream.id,
+          headers = {
+            ["Content-Type"] = "application/json"
+          },
+          body = {
+            slots = 10,
+            orderlist = { 1,2,3,4,5,6,7,8,9,10 }
+          },
+        })
+        assert.response(res).has.status(200)
+        -- wait for invalidation of the cache
+        helpers.wait_for_invalidation(cache.upstreams_dict_key(upstream.id))
+      end)
+      it("invalidates the upstream-list when deleting an upstream", function()
+        -- Making a request to populate the cache with the upstreams
+        local res = assert(client:send {
+          method = "GET",
+          path = "/status/200",
+          headers = {
+            ["Host"] = "hooks2.com"
+          }
+        })
+        assert.response(res).has.status(200)
+        -- validate that the cache is populated
+        get_cache(cache.upstreams_dict_key(upstream.id))
+        -- delete the upstream
+        local res = assert(api_client:send {
+          method = "DELETE",
+          path = "/upstreams/mybalancer",
+        })
+        assert.response(res).has.status(204)
+        -- wait for invalidation of the cache
+        helpers.wait_for_invalidation(cache.upstreams_dict_key(upstream.id))
+      end)
+      it("invalidates an upstream when updating an upstream", function()
+        -- Making a request to populate the cache with the upstream
+        local res = assert(client:send {
+          method = "GET",
+          path = "/status/200",
+          headers = {
+            ["Host"] = "hooks2.com"
+          }
+        })
+        assert.response(res).has.status(200)
+        -- validate that the cache is populated
+        get_cache(cache.upstream_key(upstream.id))
+        -- patch the upstream
+        local res = assert(api_client:send {
+          method = "PATCH",
+          path = "/upstreams/"..upstream.id,
+          headers = {
+            ["Content-Type"] = "application/json"
+          },
+          body = {
+            slots = 10,
+            orderlist = { 1,2,3,4,5,6,7,8,9,10 }
+          },
+        })
+        assert.response(res).has.status(200)
+        -- wait for invalidation of the cache
+        helpers.wait_for_invalidation(cache.upstream_key(upstream.id))
+      end)
+      it("invalidates an upstream when deleting an upstream", function()
+        -- Making a request to populate the cache with the upstream
+        local res = assert(client:send {
+          method = "GET",
+          path = "/status/200",
+          headers = {
+            ["Host"] = "hooks2.com"
+          }
+        })
+        assert.response(res).has.status(200)
+        -- validate that the cache is populated
+        get_cache(cache.upstream_key(upstream.id))
+        -- delete the upstream
+        local res = assert(api_client:send {
+          method = "DELETE",
+          path = "/upstreams/mybalancer",
+        })
+        assert.response(res).has.status(204)
+        -- wait for invalidation of the cache
+        helpers.wait_for_invalidation(cache.upstream_key(upstream.id))
+      end)
+      it("invalidates the target-history when updating an upstream", function()
+        -- Making a request to populate target history for upstream
+        local res = assert(client:send {
+          method = "GET",
+          path = "/status/200",
+          headers = {
+            ["Host"] = "hooks2.com"
+          }
+        })
+        assert.response(res).has.status(200)
+        -- validate that the cache is populated
+        get_cache(cache.targets_key(upstream.id))
+        -- patch the upstream
+        local res = assert(api_client:send {
+          method = "PATCH",
+          path = "/upstreams/"..upstream.id,
+          headers = {
+            ["Content-Type"] = "application/json"
+          },
+          body = {
+            slots = 10,
+            orderlist = { 1,2,3,4,5,6,7,8,9,10 }
+          },
+        })
+        assert.response(res).has.status(200)
+        -- wait for invalidation of the cache
+        helpers.wait_for_invalidation(cache.targets_key(upstream.id))
+      end)
+      it("invalidates the target-history when deleting an upstream", function()
+        -- Making a request to populate target history for upstream
+        local res = assert(client:send {
+          method = "GET",
+          path = "/status/200",
+          headers = {
+            ["Host"] = "hooks2.com"
+          }
+        })
+        assert.response(res).has.status(200)
+        -- validate that the cache is populated
+        get_cache(cache.targets_key(upstream.id))
+        -- delete the upstream
+        local res = assert(api_client:send {
+          method = "DELETE",
+          path = "/upstreams/mybalancer",
+        })
+        assert.response(res).has.status(204)
+        -- wait for invalidation of the cache
+        helpers.wait_for_invalidation(cache.targets_key(upstream.id))
       end)
     end)
 
+    describe("Targets entity", function()
+      local upstream
+      
+      setup(function()
+        assert(helpers.dao.apis:insert {
+          request_host = "hooks2.com",
+          upstream_url = "http://mybalancer"
+        })
+        upstream = assert(helpers.dao.upstreams:insert {
+          name = "mybalancer",
+        })
+        assert(helpers.dao.targets:insert {
+          upstream_id = upstream.id,
+          target = "mockbin.com:80",
+          weight = 10,
+        })
+      end)
+      it("invalidates the target-history when adding a target", function()
+        -- Making a request to populate target history for upstream
+        local res = assert(client:send {
+          method = "GET",
+          path = "/status/200",
+          headers = {
+            ["Host"] = "hooks2.com"
+          }
+        })
+        assert.response(res).has.status(200)
+        -- validate that the cache is populated
+        get_cache(cache.targets_key(upstream.id))
+        -- Adding a new target
+        local res = assert(api_client:send {
+          method = "POST",
+          path = "/upstreams/mybalancer/targets",
+          headers = {
+            ["Content-Type"] = "application/json"
+          },
+          body = {
+            target = "mockbin.com:80",
+            weight = 5,
+          }
+        })
+        assert.response(res).has.status(201)
+        -- wait for invalidation of the cache
+        helpers.wait_for_invalidation(cache.targets_key(upstream.id))
+        -- Making another request to re-populate target history
+        assert(client:send {
+          method = "GET",
+          path = "/status/200",
+          headers = {
+            ["Host"] = "hooks2.com"
+          }
+        })
+        -- validate that the cache is populated
+        local body = get_cache(cache.targets_key(upstream.id))
+        -- check contents
+        assert.equal(10, body[1].weight)  -- initial weight value
+        assert.equal(5, body[2].weight)   -- new weight value
+      end)
+    end)
+    
     describe("Serf events", function()
       local PID_FILE = "/tmp/serf_test.pid"
       local LOG_FILE = "/tmp/serf_test.log"
diff --git a/spec/02-integration/04-core/03-dns_spec.lua b/spec/02-integration/05-proxy/04-dns_spec.lua
similarity index 73%
rename from spec/02-integration/04-core/03-dns_spec.lua
rename to spec/02-integration/05-proxy/04-dns_spec.lua
index a6dfc7a69ba8..055e70da48c9 100644
--- a/spec/02-integration/04-core/03-dns_spec.lua
+++ b/spec/02-integration/05-proxy/04-dns_spec.lua
@@ -34,7 +34,7 @@ local function bad_tcp_server(port, duration, ...)
   return thread:start(...)
 end
 
-describe("Core DNS", function()
+describe("DNS", function()
   describe("retries", function()
     
     local retries = 3
@@ -69,7 +69,7 @@ describe("Core DNS", function()
           host = "retries.com"
         }
       }
-      assert.equals(502, r.status)
+      assert.response(r).has.status(502)
 
       -- Getting back the TCP server count of the tries
       local ok, tries = thread:join()
@@ -78,4 +78,35 @@ describe("Core DNS", function()
 
     end)
   end)
+  describe("upstream resolve failure", function()
+    
+    local client
+    
+    setup(function()
+      assert(helpers.start_kong())
+      client = helpers.proxy_client()
+
+      assert(helpers.dao.apis:insert {
+        name = "tests-retries",
+        request_host = "retries.com",
+        upstream_url = "http://now.this.does.not/exist",
+      })
+    end)
+
+    teardown(function()
+      if client then client:close() end
+      helpers.stop_kong()
+    end)
+
+    it("fails with 500", function()
+      local r = client:send {
+        method = "GET",
+        path = "/",
+        headers = {
+          host = "retries.com"
+        }
+      }
+      assert.response(r).has.status(500)
+    end)
+  end)
 end)
diff --git a/spec/02-integration/05-proxy/05-balancer_spec.lua b/spec/02-integration/05-proxy/05-balancer_spec.lua
new file mode 100644
index 000000000000..9d66464324eb
--- /dev/null
+++ b/spec/02-integration/05-proxy/05-balancer_spec.lua
@@ -0,0 +1,464 @@
+-- these tests only apply to the ring-balancer
+-- for dns-record balancing see the `dns_spec` files
+
+local helpers = require "spec.helpers"
+local cache = require "kong.tools.database_cache"
+local dao_helpers = require "spec.02-integration.02-dao.helpers"
+local PORT = 21000
+
+
+-- modified http-server. Accepts (sequentially) a number of incoming
+-- connections, and returns the number of succesful ones.
+-- Also features a timeout setting.
+local function http_server(timeout, count, port, ...)
+  local threads = require "llthreads2.ex"
+  local thread = threads.new({
+    function(timeout, count, port)
+      local socket = require "socket"
+      local server = assert(socket.tcp())
+      assert(server:setoption('reuseaddr', true))
+      assert(server:bind("*", port))
+      assert(server:listen())
+      
+      local expire = socket.gettime() + timeout
+      assert(server:settimeout(0.1))
+      
+      local success = 0
+      while count > 0 do
+        local client, err
+        client, err = server:accept()
+        if err == "timeout" then
+          if socket.gettime() > expire then
+            server:close()
+            error("timeout")
+          end
+        elseif not client then
+          server:close()
+          error(err)
+        else
+          count = count - 1
+          
+          local lines = {}
+          local line, err
+          while #lines < 7 do
+            line, err = client:receive()
+            if err then
+              break
+            else
+              table.insert(lines, line)
+            end
+          end
+
+          if err then
+            client:close()
+            server:close()
+            error(err)
+          end
+
+          local s = client:send("HTTP/1.1 200 OK\r\nConnection: close\r\n\r\n")
+          client:close()
+          if s then
+            success = success + 1
+          end
+        end
+      end
+      
+      server:close()
+      return success
+    end
+  }, timeout, count, port)
+
+  return thread:start(...)
+end
+
+dao_helpers.for_each_dao(function(kong_config)
+
+  describe("Ring-balancer #"..kong_config.database, function()
+    
+    local config_db
+    setup(function()
+      config_db = helpers.test_conf.database
+      helpers.test_conf.database = kong_config.database
+    end)
+    teardown(function()
+      helpers.test_conf.database = config_db
+      config_db = nil
+    end)
+  
+    describe("Balancing", function()
+      local client, api_client, upstream, target1, target2
+      
+      before_each(function()
+        helpers.start_kong()
+        client = helpers.proxy_client()
+        api_client = helpers.admin_client()
+
+        assert(helpers.dao.apis:insert {
+          request_host = "balancer.test",
+          upstream_url = "http://service.xyz.v1/path",
+        })
+        upstream = assert(helpers.dao.upstreams:insert {
+          name = "service.xyz.v1",
+          slots = 10,
+        })
+        target1 = assert(helpers.dao.targets:insert {
+          target = "127.0.0.1:"..PORT,
+          weight = 10,
+          upstream_id = upstream.id,
+        })
+        target2 = assert(helpers.dao.targets:insert {
+          target = "127.0.0.1:"..(PORT+1),
+          weight = 10,
+          upstream_id = upstream.id,
+        })
+      end)
+
+      after_each(function()
+        if client and api_client then
+          client:close()
+          api_client:close()
+        end
+        helpers.stop_kong()
+      end)
+
+      it("over multiple targets", function()
+        local timeout = 10
+        local requests = upstream.slots * 2 -- go round the balancer twice
+        
+        -- setup target servers
+        local server1 = http_server(timeout, requests/2, PORT)
+        local server2 = http_server(timeout, requests/2, PORT+1)
+        
+        -- Go hit them with our test requests
+        for _ = 1, requests do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/",
+            headers = {
+              ["Host"] = "balancer.test"
+            }
+          })
+          assert.response(res).has.status(200)
+        end
+        
+        -- collect server results; hitcount
+        local _, count1 = server1:join()
+        local _, count2 = server2:join()
+        
+        -- verify
+        assert.are.equal(requests/2, count1)
+        assert.are.equal(requests/2, count2)
+      end)
+      it("adding a target", function()
+        local timeout = 10
+        local requests = upstream.slots * 2 -- go round the balancer twice
+        
+        -- setup target servers
+        local server1 = http_server(timeout, requests/2, PORT)
+        local server2 = http_server(timeout, requests/2, PORT+1)
+        
+        -- Go hit them with our test requests
+        for _ = 1, requests do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/",
+            headers = {
+              ["Host"] = "balancer.test"
+            }
+          })
+          assert.response(res).has.status(200)
+        end
+        
+        -- collect server results; hitcount
+        local _, count1 = server1:join()
+        local _, count2 = server2:join()
+        
+        -- verify
+        assert.are.equal(requests/2, count1)
+        assert.are.equal(requests/2, count2)
+        
+        -- add a new target 3
+        local res = assert(api_client:send {
+          method = "POST",
+          path = "/upstreams/"..upstream.name.."/targets",
+          headers = {
+            ["Content-Type"] = "application/json"
+          },        
+          body = {
+            target = "127.0.0.1:"..(PORT+2),
+            weight = target1.weight/2 ,  -- shift proportions from 50/50 to 40/40/20
+          },
+        })
+        assert.response(res).has.status(201)
+        
+        -- wait for the change to become effective
+        helpers.wait_for_invalidation(cache.targets_key(upstream.id))
+        
+        -- now go and hit the same balancer again
+        -----------------------------------------
+        
+        -- setup target servers
+        server1 = http_server(timeout, requests * 0.4, PORT)
+        server2 = http_server(timeout, requests * 0.4, PORT+1)
+        local server3 = http_server(timeout, requests * 0.2, PORT+2)
+        
+        -- Go hit them with our test requests
+        for _ = 1, requests do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/",
+            headers = {
+              ["Host"] = "balancer.test"
+            }
+          })
+          assert.response(res).has.status(200)
+        end
+        
+        -- collect server results; hitcount
+        _, count1 = server1:join()
+        _, count2 = server2:join()
+        local _, count3 = server3:join()
+        
+        -- verify
+        assert.are.equal(requests * 0.4, count1)
+        assert.are.equal(requests * 0.4, count2)
+        assert.are.equal(requests * 0.2, count3)
+      end)
+      it("removing a target", function()
+        local timeout = 10
+        local requests = upstream.slots * 2 -- go round the balancer twice
+        
+        -- setup target servers
+        local server1 = http_server(timeout, requests/2, PORT)
+        local server2 = http_server(timeout, requests/2, PORT+1)
+        
+        -- Go hit them with our test requests
+        for _ = 1, requests do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/",
+            headers = {
+              ["Host"] = "balancer.test"
+            }
+          })
+          assert.response(res).has.status(200)
+        end
+        
+        -- collect server results; hitcount
+        local _, count1 = server1:join()
+        local _, count2 = server2:join()
+        
+        -- verify
+        assert.are.equal(requests/2, count1)
+        assert.are.equal(requests/2, count2)
+        
+        -- modify weight for target 2, set to 0
+        local res = assert(api_client:send {
+          method = "POST",
+          path = "/upstreams/"..upstream.name.."/targets",
+          headers = {
+            ["Content-Type"] = "application/json"
+          },        
+          body = {
+            target = target2.target,
+            weight = 0,   -- disable this target
+          },
+        })
+        assert.response(res).has.status(201)
+        
+        -- wait for the change to become effective
+        helpers.wait_for_invalidation(cache.targets_key(target2.upstream_id))
+        
+        -- now go and hit the same balancer again
+        -----------------------------------------
+        
+        -- setup target servers
+        server1 = http_server(timeout, requests, PORT)
+        
+        -- Go hit them with our test requests
+        for _ = 1, requests do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/",
+            headers = {
+              ["Host"] = "balancer.test"
+            }
+          })
+          assert.response(res).has.status(200)
+        end
+        
+        -- collect server results; hitcount
+        _, count1 = server1:join()
+        
+        -- verify all requests hit server 1
+        assert.are.equal(requests, count1)
+      end)
+      it("modifying target weight", function()
+        local timeout = 10
+        local requests = upstream.slots * 2 -- go round the balancer twice
+        
+        -- setup target servers
+        local server1 = http_server(timeout, requests/2, PORT)
+        local server2 = http_server(timeout, requests/2, PORT+1)
+        
+        -- Go hit them with our test requests
+        for _ = 1, requests do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/",
+            headers = {
+              ["Host"] = "balancer.test"
+            }
+          })
+          assert.response(res).has.status(200)
+        end
+        
+        -- collect server results; hitcount
+        local _, count1 = server1:join()
+        local _, count2 = server2:join()
+        
+        -- verify
+        assert.are.equal(requests/2, count1)
+        assert.are.equal(requests/2, count2)
+        
+        -- modify weight for target 2
+        local res = assert(api_client:send {
+          method = "POST",
+          path = "/upstreams/"..target2.upstream_id.."/targets",
+          headers = {
+            ["Content-Type"] = "application/json"
+          },        
+          body = {
+            target = target2.target,
+            weight = target1.weight * 1.5,   -- shift proportions from 50/50 to 40/60
+          },
+        })
+        assert.response(res).has.status(201)
+        
+        -- wait for the change to become effective
+        helpers.wait_for_invalidation(cache.targets_key(target2.upstream_id))
+        
+        -- now go and hit the same balancer again
+        -----------------------------------------
+        
+        -- setup target servers
+        server1 = http_server(timeout, requests * 0.4, PORT)
+        server2 = http_server(timeout, requests * 0.6, PORT+1)
+        
+        -- Go hit them with our test requests
+        for _ = 1, requests do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/",
+            headers = {
+              ["Host"] = "balancer.test"
+            }
+          })
+          assert.response(res).has.status(200)
+        end
+        
+        -- collect server results; hitcount
+        _, count1 = server1:join()
+        _, count2 = server2:join()
+        
+        -- verify
+        assert.are.equal(requests * 0.4, count1)
+        assert.are.equal(requests * 0.6, count2)
+      end)
+      it("failure due to targets all 0 weight", function()
+        local timeout = 10
+        local requests = upstream.slots * 2 -- go round the balancer twice
+        
+        -- setup target servers
+        local server1 = http_server(timeout, requests/2, PORT)
+        local server2 = http_server(timeout, requests/2, PORT+1)
+        
+        -- Go hit them with our test requests
+        for _ = 1, requests do
+          local res = assert(client:send {
+            method = "GET",
+            path = "/",
+            headers = {
+              ["Host"] = "balancer.test"
+            }
+          })
+          assert.response(res).has.status(200)
+        end
+        
+        -- collect server results; hitcount
+        local _, count1 = server1:join()
+        local _, count2 = server2:join()
+        
+        -- verify
+        assert.are.equal(requests/2, count1)
+        assert.are.equal(requests/2, count2)
+
+        -- modify weight for both targets, set to 0
+        local res = assert(api_client:send {
+          method = "POST",
+          path = "/upstreams/"..upstream.name.."/targets",
+          headers = {
+            ["Content-Type"] = "application/json"
+          },        
+          body = {
+            target = target1.target,
+            weight = 0,   -- disable this target
+          },
+        })
+        assert.response(res).has.status(201)
+
+        res = assert(api_client:send {
+          method = "POST",
+          path = "/upstreams/"..upstream.name.."/targets",
+          headers = {
+            ["Content-Type"] = "application/json"
+          },        
+          body = {
+            target = target2.target,
+            weight = 0,   -- disable this target
+          },
+        })
+        assert.response(res).has.status(201)
+
+        -- wait for the change to become effective
+        helpers.wait_for_invalidation(cache.targets_key(target2.upstream_id))
+        
+        -- now go and hit the same balancer again
+        -----------------------------------------
+        
+        res = assert(client:send {
+          method = "GET",
+          path = "/",
+          headers = {
+            ["Host"] = "balancer.test"
+          }
+        })
+
+        assert.response(res).has.status(503)
+      end)
+      it("failure due to no targets", function()
+        -- insert additional api + upstream with no targets
+        assert(helpers.dao.apis:insert {
+          request_host = "balancer.test2",
+          upstream_url = "http://service.xyz.v2/path",
+        })
+        upstream = assert(helpers.dao.upstreams:insert {
+          name = "service.xyz.v2",
+          slots = 10,
+        })
+
+        -- Go hit it with a request
+        local res = assert(client:send {
+          method = "GET",
+          path = "/",
+          headers = {
+            ["Host"] = "balancer.test2"
+          }
+        })
+
+        assert.response(res).has.status(503)
+      end)
+    end)
+  end)
+
+end) -- for 'database type'
diff --git a/spec/helpers.lua b/spec/helpers.lua
index 92f88cf1dc1f..33b3bcf49cc3 100644
--- a/spec/helpers.lua
+++ b/spec/helpers.lua
@@ -794,6 +794,25 @@ local function clean_prefix(prefix)
   end
 end
 
+--- Waits for invalidation of a cached key by polling the mgt-api
+-- and waiting for a 404 response.
+-- @name wait_for_invalidation
+-- @param key the cache-key to check
+-- @param timeout (optional) in seconds, defaults to 10.
+local function wait_for_invalidation(key, timeout)
+  local api_client = admin_client()
+  timeout = timeout or 10
+  wait_until(function()
+    local res = assert(api_client:send {
+      method = "GET",
+      path = "/cache/"..key,
+      headers = {}
+    })
+    res:read_body()
+    return res.status == 404
+  end, timeout)
+end
+
 ----------
 -- Exposed
 ----------
@@ -824,6 +843,7 @@ return {
   proxy_ssl_client = proxy_ssl_client,
   prepare_prefix = prepare_prefix,
   clean_prefix = clean_prefix,
+  wait_for_invalidation = wait_for_invalidation,
   
   -- miscellaneous
   intercept = intercept,