restfully_accessible.rb in yao-0.8.0

- old
+ new

@@ -3,11 +3,11 @@
 module Yao::Resources
   module RestfullyAccessible
     def self.extended(base)
       base.class_eval do
         class << self
-          attr_accessor :resource_name, :resources_name
+          attr_accessor :resource_name, :resources_name, :resources_detail_available
 
           extend Forwardable
           %w(get post put delete).each do |method_name|
             def_delegator :client, method_name, method_name.upcase
           end
@@ -32,10 +32,14 @@
 
     def admin=(bool)
       @admin = bool
     end
 
+    def return_single_on_querying
+      @return_single_on_querying
+    end
+
     def return_single_on_querying=(bool)
       @return_single_on_querying = bool
     end
 
     def resources_path
@@ -63,113 +67,146 @@
       else
         yield
       end
     end
 
-    def with_resources_path(path, &blk)
-      original = @resources_path
-      @resources_path = path
-      result = yield
-      @resources_path = original
+    # @param query [Hash]
+    # @return [Yao::Resources::*]
+    # @return [Array<Yao::Resources::*]
+    def list(query={})
 
-      result
-    end
+      url = if resources_detail_available
+        # If the resource has 'detail', #list tries to GET /${resourece}/detail
+        # For example.
+        #
+        #   GET /servers/detail
+        #   GET /flavors/detail
+        #
+        create_url('detail')
+      else
+        create_url
+      end
 
-    # restful methods
-    def list(query={})
-      json = GET(create_url([api_version, resources_path]), query).body
-      if @return_single_on_querying && !query.empty?
-        return_resource(resource_from_json(json))
+      json = GET(url, query).body
+      if return_single_on_querying && !query.empty?
+        # returns Yao::Resources::*
+        resource_from_json(json)
       else
-        return_resources(resources_from_json(json))
+        # returns Array of Yao::Resources::*
+        resources_from_json(json)
       end
     end
 
+    # @note .list is defined to keep backward compatibility and will be deprecated
+    alias :list_detail :list
+
+    # @param id_or_name_or_permalink [Stirng]
+    # @param query [Hash]
+    # @return [Yao::Resources::*]
     def get(id_or_name_or_permalink, query={})
       res = if id_or_name_or_permalink.start_with?("http://", "https://")
               GET(id_or_name_or_permalink, query)
             elsif uuid?(id_or_name_or_permalink)
-              GET(create_url([api_version, resources_path, id_or_name_or_permalink]), query)
+              GET(create_url(id_or_name_or_permalink), query)
             else
               get_by_name(id_or_name_or_permalink, query)
             end
 
-      return_resource(resource_from_json(res.body))
+      resource_from_json(res.body)
     end
     alias find get
 
     def find_by_name(name, query={})
       list(query.merge({"name" => name}))
     end
 
+    # @param resource_params [Hash]
+    # @return [Yao::Resources::*]
     def create(resource_params)
       params = {
         resource_name_in_json => resource_params
       }
-      res = POST(create_url([api_version, resources_path])) do |req|
+      res = POST(create_url) do |req|
         req.body = params.to_json
         req.headers['Content-Type'] = 'application/json'
       end
-      return_resource(resource_from_json(res.body))
+      resource_from_json(res.body)
     end
 
+    # @param id [String]
+    # @return [Yao::Resources::*]
     def update(id, resource_params)
       params = {
         resource_name_in_json => resource_params
       }
-      res = PUT(create_url([api_version, resources_path, id])) do |req|
+      res = PUT(create_url(id)) do |req|
         req.body = params.to_json
         req.headers['Content-Type'] = 'application/json'
       end
-      return_resource(resource_from_json(res.body))
+      resource_from_json(res.body)
     end
 
+    # @param id [String]
+    # @return [String]
     def destroy(id)
-      res = DELETE(create_url([api_version, resources_path, id]))
+      res = DELETE(create_url(id))
       res.body
     end
 
     private
-    def create_url(paths)
+
+    # returns pathname of resource URL
+    # @param subpath [String]
+    # @return [String]
+    def create_url(subpath='')
+      paths = [ api_version, resources_path, subpath ]
       paths.select{|s| s != ''}.join('/')
     end
 
+    # @return [String]
     def resource_name_in_json
       @_resource_name_in_json ||= resource_name.sub(/^os-/, "").tr("-", "_")
     end
 
-    def resource_from_json(json)
-      json[resource_name_in_json]
-    end
-
-    def resources_from_json(json)
+    # @return [String]
+    def resources_name_in_json
       @resources_name_in_json ||= resources_name.sub(/^os-/, "").tr("-", "_")
-      json[@resources_name_in_json]
     end
 
-    def return_resource(d)
-      new(d)
+    # @param json [Hash]
+    # @return [Yao::Resources::*]
+    def resource_from_json(json)
+      attribute = json[resource_name_in_json]
+      new(attribute)
     end
 
-    def return_resources(arr)
-      arr.map{|d| return_resource(d) }
+    # @param json [Hash]
+    # @return [Array<Yao::Resources::*>]
+    def resources_from_json(json)
+      json[resources_name_in_json].map { |attribute|
+        new(attribute) # instance of Yao::Resources::*
+      }
     end
 
     def uuid?(str)
       /^[\da-f]{8}-([\da-f]{4}-){3}[\da-f]{12}$/ === str
     end
 
+    # At first, search by ID. If nothing is found, search by name.
+    # @param name [String]
+    # @param query [Hash]
+    # @return [Yao::Resources::*]
     def get_by_name(name, query={})
-      # At first, search by ID. If nothing is found, search by name.
+
       begin
-        GET(create_url([api_version, resources_path, name]), query)
+        GET(create_url(name), query)
       rescue => e
         raise e unless e.class == Yao::ItemNotFound || e.class == Yao::NotFound
         item = find_by_name(name)
         if item.size > 1
           raise Yao::TooManyItemFonud.new("More than one resource exists with the name '#{name}'")
         end
-        GET(create_url([api_version, resources_path, item.first.id]), query)
+        GET(create_url(item.first.id), query)
       end
     end
   end
 end