cloudinary 1.20.0 → 1.23.0

data/lib/cloudinary/api.rb

@@ -1,21 +1,33 @@
 class Cloudinary::Api
   extend Cloudinary::BaseApi
 
+  # Tests the reachability of the Cloudinary API.
+  #
+  # @param [Hash] options The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response] The current status of the Cloudinary servers
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#ping
   def self.ping(options={})
     call_api(:get, "ping", {}, options)
   end
 
-  # Gets account usage details
+  # Gets cloud usage details.
   #
-  # Get a report on the status of your Cloudinary account usage details, including
-  # storage, bandwidth, requests, number of resources, and add-on usage.
+  # Returns a report detailing your current Cloudinary cloud usage details, including
+  # storage, bandwidth, requests, number of assets, and add-on usage.
   # Note that numbers are updated periodically.
   #
-  # @see https://cloudinary.com/documentation/admin_api#get_account_usage_details Get account usage details
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#usage Admin API} documentation.
   #
-  # @param [Hash] options Additional options
   # @return [Cloudinary::Api::Response]
+  #
   # @raise [Cloudinary::Api:Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#usage
   def self.usage(options={})
     uri = 'usage'
     date = options[:date]
@@ -25,39 +37,133 @@ class Cloudinary::Api
     call_api(:get, uri, {}, options)
   end
 
+  # Lists all uploaded assets filtered by any specified options.
+  #
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_resources Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_resources
   def self.resource_types(options={})
     call_api(:get, "resources", {}, options)
   end
 
+  # Lists all uploaded assets filtered by any specified options.
+  #
+  # see https://cloudinary.com/documentation/admin_api#get_resources Get all images
+  #
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_resources Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_resources
   def self.resources(options={})
     resource_type = options[:resource_type] || "image"
     type          = options[:type]
     uri           = "resources/#{resource_type}"
     uri           += "/#{type}" unless type.blank?
-    call_api(:get, uri, only(options, :next_cursor, :max_results, :prefix, :tags, :context, :moderations, :direction, :start_at), options)
+    call_api(:get, uri, only(options, :next_cursor, :max_results, :prefix, :tags, :context, :moderations, :direction, :start_at, :metadata), options)
   end
 
+  # Lists assets with the specified tag.
+  #
+  # This method does not return matching deleted assets, even if they have been backed up.
+  #
+  # @param [String] tag     The tag value.
+  # @param [Hash]   options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_resources_by_tag Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_resources_by_tag
   def self.resources_by_tag(tag, options={})
     resource_type = options[:resource_type] || "image"
     uri           = "resources/#{resource_type}/tags/#{tag}"
-    call_api(:get, uri, only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction), options)
+    call_api(:get, uri, only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction, :metadata), options)
   end
 
+  # Lists assets currently in the specified moderation queue and status.
+  #
+  # @param [String] kind    Type of image moderation queue to list.
+  #                         Valid values:  "manual", "webpurify", "aws_rek", or "metascan".
+  # @param [String] status  Only assets with this moderation status will be returned.
+  #                         Valid values: "pending", "approved", "rejected".
+  # @param [Hash]   options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_resources_in_moderation_queues Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_resources_in_moderation_queues
   def self.resources_by_moderation(kind, status, options={})
     resource_type = options[:resource_type] || "image"
     uri           = "resources/#{resource_type}/moderations/#{kind}/#{status}"
-    call_api(:get, uri, only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction), options)
+    call_api(:get, uri, only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction, :metadata), options)
   end
 
+  # Lists assets with the specified contextual metadata.
+  #
+  # This method does not return matching deleted assets, even if they have been backed up.
+  #
+  # @param [String] key     Only assets with this context key are returned.
+  # @param [String] value   Only assets with this context value for the specified context key are returned.
+  #                         If this parameter is not provided, all assets with the specified context key are returned,
+  #                         regardless of the key value.
+  # @param [Hash]   options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_resources_by_context Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_resources_by_context
   def self.resources_by_context(key, value=nil, options={})
     resource_type = options[:resource_type] || "image"
     uri           = "resources/#{resource_type}/context"
-    params = only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction,:key,:value)
+    params = only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction, :key, :value, :metadata)
     params[:key] = key
     params[:value] = value
     call_api(:get, uri, params, options)
   end
 
+  # Returns the details of the specified asset and all its derived assets by asset id.
+  # 
+  # Note that if you only need details about the original asset,
+  # you can also use the Uploader::upload or Uploader::explicit methods, which return the same information and
+  # are not rate limited.
+  # 
+  # @param [String] asset_id The Asset ID of the asset.
+  # @param [Hash]   options  The optional parameters. See the <a href=https://cloudinary.com/documentation/admin_api#get_the_details_of_a_single_resource target="_blank"> Admin API</a> documentation.
+  # 
+  # @return [Cloudinary::Api::Response]
+  # 
+  # @see https://cloudinary.com/documentation/admin_api#get_the_details_of_a_single_resource
+  def self.resource_by_asset_id(asset_id, options={})
+    uri    = "resources/#{asset_id}"
+    params = prepare_resource_details_params(options)
+    call_api(:get, uri, params, options)
+  end
+  
+  # Lists assets with the specified public IDs.
+  #
+  # @param [String|Array] public_ids The requested public_ids (up to 100).
+  # @param [Hash]          options    The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_resources Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_resources
   def self.resources_by_ids(public_ids, options={})
     resource_type = options[:resource_type] || "image"
     type          = options[:type] || "upload"
@@ -65,28 +171,58 @@ class Cloudinary::Api
     call_api(:get, uri, only(options, :tags, :context, :moderations).merge(:public_ids => public_ids), options)
   end
 
+  # Lists assets with the specified asset IDs.
+  #
+  # @param [Object] asset_ids The requested asset IDs.
+  # @param [Hash]   options   The optional parameters. See the
+  # <a href=https://cloudinary.com/documentation/admin_api#get_resources target="_blank"> Admin API</a> documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_resources
+  def self.resources_by_asset_ids(asset_ids, options={})
+    uri = "resources/by_asset_ids"
+    params = only(options, :public_ids, :tags, :moderations, :context)
+    params[:asset_ids] = asset_ids
+    call_api(:get, uri, params, options)
+  end
+
+  # Returns the details of the specified asset and all its derived assets.
+  #
+  # Note that if you only need details about the original asset,
+  # you can also use the Uploader::upload or Uploader::explicit methods, which return the same information and
+  # are not rate limited.
+  #
+  # @param [String] public_id The public ID of the asset.
+  # @param [Hash]   options   The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_the_details_of_a_single_resource Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_the_details_of_a_single_resource
   def self.resource(public_id, options={})
     resource_type = options[:resource_type] || "image"
     type          = options[:type] || "upload"
     uri           = "resources/#{resource_type}/#{type}/#{public_id}"
-    call_api(:get, uri,
-             only(options,
-                  :cinemagraph_analysis,
-                  :colors,
-                  :coordinates,
-                  :exif,
-                  :faces,
-                  :image_metadata,
-                  :max_results,
-                  :pages,
-                  :phash,
-                  :quality_analysis,
-                  :derived_next_cursor,
-                  :accessibility_analysis,
-                  :versions
-             ), options)
+    call_api(:get, uri, prepare_resource_details_params(options), options)
   end
 
+  # Reverts to the latest backed up version of the specified deleted assets.
+  #
+  # @param [String|Array] public_ids The public IDs of the backed up assets to restore. They can be existing or
+  #   deleted assets.
+  # @param [Hash]          options    The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#restore_resources Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#restore_resources
   def self.restore(public_ids, options={})
     resource_type = options[:resource_type] || "image"
     type          = options[:type] || "upload"
@@ -94,6 +230,20 @@ class Cloudinary::Api
     call_api(:post, uri, { :public_ids => public_ids, :versions => options[:versions] }, options)
   end
 
+  # Updates details of an existing asset.
+  #
+  # Update one or more of the attributes associated with a specified asset. Note that you can also update
+  # most attributes of an existing asset using the Uploader::explicit method, which is not rate limited.
+  #
+  # @param [String|Array] public_id The public ID of the asset to update.
+  # @param [Hash]          options   The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#update_details_of_an_existing_resource Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#update_details_of_an_existing_resource
   def self.update(public_id, options={})
     resource_type  = options[:resource_type] || "image"
     type           = options[:type] || "upload"
@@ -118,6 +268,17 @@ class Cloudinary::Api
     call_api(:post, uri, update_options, options)
   end
 
+  # Deletes the specified assets.
+  #
+  # @param [String|Array] public_ids The public IDs of the assets to delete (up to 100).
+  # @param [Hash]          options    The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#sdelete_resources Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_resources
   def self.delete_resources(public_ids, options={})
     resource_type = options[:resource_type] || "image"
     type          = options[:type] || "upload"
@@ -125,6 +286,20 @@ class Cloudinary::Api
     call_api(:delete, uri, delete_resource_params(options, :public_ids => public_ids ), options)
   end
 
+  # Deletes assets by prefix.
+  #
+  # Delete up to 1000 original assets, along with their derived assets, where the public ID starts with the
+  # specified prefix.
+  #
+  # @param [String] prefix  The Public ID prefix.
+  # @param [Hash]   options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#delete_resources Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_resources
   def self.delete_resources_by_prefix(prefix, options={})
     resource_type = options[:resource_type] || "image"
     type          = options[:type] || "upload"
@@ -132,6 +307,18 @@ class Cloudinary::Api
     call_api(:delete, uri, delete_resource_params(options, :prefix => prefix), options)
   end
 
+  # Deletes all assets of the specified asset and delivery type, including their derived assets.
+  #
+  # Supports deleting up to a maximum of 1000 original assets in a single call.
+  #
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#delete_resources Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # https://cloudinary.com/documentation/admin_api#delete_resources
   def self.delete_all_resources(options={})
     resource_type = options[:resource_type] || "image"
     type          = options[:type] || "upload"
@@ -139,23 +326,53 @@ class Cloudinary::Api
     call_api(:delete, uri, delete_resource_params(options, :all => true ), options)
   end
 
+  # Deletes assets with the specified tag, including their derived assets.
+  #
+  # Supports deleting up to a maximum of 1000 original assets in a single call.
+  #
+  # @param [String] tag     The tag value of the assets to delete.
+  # @param [Hash]   options The optional parameters. See the
+  # {https://cloudinary.com/documentation/admin_api#delete_resources_by_tags Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_resources_by_tags
   def self.delete_resources_by_tag(tag, options={})
     resource_type = options[:resource_type] || "image"
     uri           = "resources/#{resource_type}/tags/#{tag}"
     call_api(:delete, uri, delete_resource_params(options), options)
   end
 
+  # Deletes the specified derived assets by derived asset ID.
+  #
+  # The derived asset IDs for a particular original asset are returned when calling the {.resource} method to
+  # return the details of a single asset.
+  #
+  # @param [String|Array] derived_resource_ids The derived asset IDs (up to 100 ids).
+  # @param [Hash]          options              The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api##delete_resources
   def self.delete_derived_resources(derived_resource_ids, options={})
     uri = "derived_resources"
     call_api(:delete, uri, { :derived_resource_ids => derived_resource_ids }, options)
   end
 
-  # Delete derived resources identified by transformation for the provided public_ids
-  # @param [String|Array] public_ids The resources the derived resources belong to
-  # @param [String|Hash|Array] transformations the transformation(s) associated with the derived resources
-  # @param [Hash] options
-  # @option options [String] :resource_type ("image")
-  # @option options [String] :type ("upload")
+  # Deletes derived assets identified by transformation and public_ids.
+  #
+  # @param [String|Array]      public_ids      The public IDs for which you want to delete derived assets.
+  # @param [String|Array|Hash] transformations The transformation(s) associated with the derived assets to delete.
+  # @param [Hash]              options         The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#resources Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
   def self.delete_derived_by_transformation(public_ids, transformations, options={})
     resource_type = options[:resource_type] || "image"
     type          = options[:type] || "upload"
@@ -166,124 +383,413 @@ class Cloudinary::Api
     call_api(:delete, uri, params, options)
   end
 
+  # Lists all the tags currently used for a specified asset type.
+  #
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_tags Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_tags
   def self.tags(options={})
     resource_type = options[:resource_type] || "image"
     uri           = "tags/#{resource_type}"
     call_api(:get, uri, only(options, :next_cursor, :max_results, :prefix), options)
   end
 
+  # Lists stored transformations.
+  #
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_transformations Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_transformations
   def self.transformations(options={})
     call_api(:get, "transformations", only(options, :named, :next_cursor, :max_results), options)
   end
 
+  # Returns the details of a single transformation.
+  #
+  # @param [String|Array] transformation The transformation. Can be either a string or an array of parameters.
+  #                                      For example: "w_150,h_100,c_fill" or array("width" => 150, "height" =>
+  #                                      100,"crop" => "fill").
+  # @param [Hash]         options        The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_transformation_details Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_transformation_details
   def self.transformation(transformation, options={})
-    call_api(:get, "transformations/#{transformation_string(transformation)}", only(options, :next_cursor, :max_results), options)
+    params                  = only(options, :next_cursor, :max_results)
+    params[:transformation] = Cloudinary::Utils.build_eager(transformation)
+    call_api(:get, "transformations", params, options)
   end
 
+  # Deletes the specified stored transformation.
+  #
+  # Deleting a transformation also deletes all the stored derived assets based on this transformation (up to 1000).
+  # The method returns an error if there are more than 1000 derived assets based on this transformation.
+  #
+  # @param [String|Hash] transformation The transformation to delete. Can be either a string or an array of
+  #                                     parameters. For example:
+  #                                     "w_150,h_100,c_fill" or !{"width" => 150, "height" => 100,"crop" => "fill"}.
+  # @param [Hash]         options       The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#delete_transformation Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_transformation
   def self.delete_transformation(transformation, options={})
-    call_api(:delete, "transformations/#{transformation_string(transformation)}", {}, options)
+    call_api(:delete, "transformations", {:transformation => Cloudinary::Utils.build_eager(transformation)}, options)
   end
 
-  # updates - supports:
-  #   "allowed_for_strict" boolean
-  #   "unsafe_update" transformation params - updates a named transformation parameters without regenerating existing images
+  # Updates the specified transformation.
+  #
+  # @param [String|Hash] transformation The transformation. Can be either a string or an array of parameters.
+  #                                     For example: "w_150,h_100,c_fill" or !{"width" => 150, "height" =>
+  #                                     100,"crop" => "fill"}.
+  # @param [Hash]        updates        The update parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#update_transformation Admin API} documentation.
+  # @param [Hash]        options        The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#update_transformation
   def self.update_transformation(transformation, updates, options={})
-    params                 = only(updates, :allowed_for_strict)
-    params[:unsafe_update] = transformation_string(updates[:unsafe_update]) if updates[:unsafe_update]
-    call_api(:put, "transformations/#{transformation_string(transformation)}", params, options)
+    params                  = only(updates, :allowed_for_strict)
+    params[:unsafe_update]  = Cloudinary::Utils.build_eager(updates[:unsafe_update]) if updates[:unsafe_update]
+    params[:transformation] = Cloudinary::Utils.build_eager(transformation)
+    call_api(:put, "transformations", params, options)
   end
 
+  # Creates a named transformation.
+  #
+  # @param [String]      name       The name of the transformation.
+  # @param [String|Hash] definition The transformation. Can be a string or a hash. For example:
+  #                                 "w_150,h_100,c_fill" or !{"width" => 150, "height" => 100, "crop" => "fill"}.
+  # @param [Hash]        options    The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#create_named_transformation
   def self.create_transformation(name, definition, options={})
-    call_api(:post, "transformations/#{name}", { :transformation => transformation_string(definition) }, options)
+    params = {
+      :name => name,
+      :transformation => Cloudinary::Utils.build_eager(definition)
+    }
+
+    call_api(:post, "transformations", params, options)
   end
 
-  # upload presets
+  # Lists existing upload presets.
+  #
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_upload_presets Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_upload_presets
   def self.upload_presets(options={})
     call_api(:get, "upload_presets", only(options, :next_cursor, :max_results), options)
   end
 
+  # Retrieves the details of the specified upload preset.
+  #
+  # @param [String] name The name of the upload preset.
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_the_details_of_a_single_upload_preset Admin API}
+  #   documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_the_details_of_a_single_upload_preset
   def self.upload_preset(name, options={})
     call_api(:get, "upload_presets/#{name}", only(options, :max_results), options)
   end
 
+  # Deletes the specified upload preset.
+  #
+  # @param [String] The name of the upload preset to delete.
+  # @param [Hash] options The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_an_upload_preset
   def self.delete_upload_preset(name, options={})
     call_api(:delete, "upload_presets/#{name}", {}, options)
   end
 
+  # Updates the specified upload preset.
+  #
+  # @param [String] name The name of the upload preset.
+  # @param [Hash] options The optional parameters. See the
+  # {https://cloudinary.com/documentation/admin_api#update_an_upload_preset Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#update_an_upload_preset
   def self.update_upload_preset(name, options={})
     params = Cloudinary::Uploader.build_upload_params(options)
-    call_api(:put, "upload_presets/#{name}", params.merge(only(options, :unsigned, :disallow_public_id)), options)
+    call_api(:put, "upload_presets/#{name}", params.merge(only(options, :unsigned, :disallow_public_id, :live)), options)
   end
 
+  # Creates a new upload preset.
+  #
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#create_an_upload_preset Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#create_an_upload_preset
   def self.create_upload_preset(options={})
     params = Cloudinary::Uploader.build_upload_params(options)
-    call_api(:post, "upload_presets", params.merge(only(options, :name, :unsigned, :disallow_public_id)), options)
+    call_api(:post, "upload_presets", params.merge(only(options, :name, :unsigned, :disallow_public_id, :live)), options)
   end
 
+  # Lists all root folders.
+  #
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_root_folders Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_root_folders
   def self.root_folders(options={})
     params = only(options, :max_results, :next_cursor)
     call_api(:get, "folders", params, options)
   end
 
+  # Lists sub-folders.
+  #
+  # Returns the name and path of all the sub-folders of a specified parent folder. Limited to 2000 results.
+  #
+  # @param [String] of_folder_path The parent folder.
+  # @param [Hash]   options        The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_subfolders Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_subfolders
   def self.subfolders(of_folder_path, options={})
     params = only(options, :max_results, :next_cursor)
     call_api(:get, "folders/#{of_folder_path}", params, options)
   end
 
+  # Deletes an empty folder.
+  #
+  # The specified folder cannot contain any assets, but can have empty descendant sub-folders.
+  #
+  # @param [String] path    The full path of the empty folder to delete.
+  # @param [Hash]   options The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_folder
   def self.delete_folder(path, options={})
     call_api(:delete, "folders/#{path}", {}, options)
   end
 
+  # Creates a new empty folder.
+  #
+  # @param [String] folder_name The full path of the new folder to create.
+  # @param [Hash]   options     The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#create_folder
   def self.create_folder(folder_name, options={})
     call_api(:post, "folders/#{folder_name}", {}, options)
   end
 
+  # Lists upload mappings by folder and its mapped template (URL).
+  #
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#get_upload_mapping Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_upload_mappings
   def self.upload_mappings(options={})
     params = only(options, :next_cursor, :max_results)
     call_api(:get, :upload_mappings, params, options)
   end
 
+  # Returns the details of the specified upload mapping.
+  #
+  # Retrieve the mapped template (URL) of a specified upload mapping folder.
+  #
+  # @param [String] name    The name of the upload mapping folder.
+  # @param [Hash]   options The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_the_details_of_a_single_upload_mapping
   def self.upload_mapping(name=nil, options={})
     call_api(:get, 'upload_mappings', { :folder => name }, options)
   end
 
+  # Deletes an upload mapping.
+  #
+  # @param [String] name    The name of the upload mapping folder to delete.
+  # @param [Hash]   options The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_an_upload_mapping
   def self.delete_upload_mapping(name, options={})
     call_api(:delete, 'upload_mappings', { :folder => name }, options)
   end
 
+  # Updates an existing upload mapping with a new template (URL).
+  #
+  # @param [String] name The name of the upload mapping folder to remap.
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#update_an_upload_mapping Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#update_an_upload_mapping
   def self.update_upload_mapping(name, options={})
     params          = only(options, :template)
     params[:folder] = name
     call_api(:put, 'upload_mappings', params, options)
   end
 
+  # Creates a new upload mapping.
+  #
+  # @param [String] name The name of the folder to map.
+  # @param [Hash] options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#create_an_upload_mapping Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#create_an_upload_mapping
   def self.create_upload_mapping(name, options={})
     params          = only(options, :template)
     params[:folder] = name
     call_api(:post, 'upload_mappings', params, options)
   end
 
+  # Creates a new, custom streaming profile.
+  #
+  # @param [String] name    The name to assign to the new streaming profile.
+  #                         The name is case-insensitive and can contain alphanumeric characters, underscores (_) and
+  #                         hyphens (-). If the name is of a predefined profile, the profile will be modified.
+  # @param [Hash]   options The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#create_a_streaming_profile Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#create_a_streaming_profile
   def self.create_streaming_profile(name, options={})
-      params = only(options, :display_name, :representations)
-      params[:representations] = params[:representations].map do |r|
-        {:transformation => Cloudinary::Utils.generate_transformation_string(r[:transformation])}
-      end.to_json
-      params[:name] = name
-      call_api(:post, 'streaming_profiles', params, options)
+    params = only(options, :display_name, :representations)
+    params[:representations] = params[:representations].map do |r|
+      {:transformation => Cloudinary::Utils.generate_transformation_string(r[:transformation])}
+    end.to_json
+    params[:name] = name
+    call_api(:post, 'streaming_profiles', params, options)
   end
 
+  # Lists streaming profiles including built-in and custom profiles.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_adaptive_streaming_profiles
   def self.list_streaming_profiles
     call_api(:get, 'streaming_profiles', {}, {})
   end
 
+  # Deletes or reverts the specified streaming profile.
+  #
+  # For custom streaming profiles, deletes the specified profile.
+  # For built-in streaming profiles, if the built-in profile was modified, reverts the profile to the original
+  # settings.
+  # For built-in streaming profiles that have not been modified, the Delete method returns an error.
+  #
+  # @param [String] name    The name of the streaming profile to delete or revert.
+  # @param [Hash]   options The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_or_revert_the_specified_streaming_profile
   def self.delete_streaming_profile(name, options={})
     call_api(:delete, "streaming_profiles/#{name}", {}, options)
   end
 
+  # Gets details of a single streaming profile by name.
+  #
+  # @param [String] name    The identification name of the streaming profile.
+  # @param [Hash]   options The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_details_of_a_single_streaming_profile
   def self.get_streaming_profile(name, options={})
     call_api(:get, "streaming_profiles/#{name}", {}, options)
   end
 
+  # Updates an existing streaming profile.
+  #
+  # You can update both custom and built-in profiles. The specified list of representations replaces the previous list.
+  #
+  # @param [String] name    The name of the streaming profile to update.
+  # @param [Hash]   options The optional parameters. See the
+  # {https://cloudinary.com/documentation/admin_api#create_a_streaming_profile Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#create_a_streaming_profile
   def self.update_streaming_profile(name, options={})
     params = only(options, :display_name, :representations)
     params[:representations] = params[:representations].map do |r|
@@ -292,73 +798,98 @@ class Cloudinary::Api
     call_api(:put, "streaming_profiles/#{name}", params, options)
   end
 
-  # Update resources access mode. Resources are selected by the prefix
-  # @param [String] access_mode the access mode to set the resources to
-  # @param [String] prefix The prefix by which to filter applicable resources
-  # @param [Object] options    additional options
-  # @option options [String] :resource_type ("image") the type of resources to modify
-  # @option options [Fixnum] :max_results (nil) the maximum resources to process in a single invocation
-  # @option options [String] :next_cursor (nil) provided by a previous call to the method
+  # Update resources access mode. Resources are selected by the prefix.
+  #
+  # @param [String] access_mode The access mode to set the resources to.
+  # @param [String] prefix      The prefix by which to filter applicable resources
+  # @param [Hash]   options     The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#examples-8
   def self.update_resources_access_mode_by_prefix(access_mode, prefix, options = {})
-
-      update_resources_access_mode(access_mode, :prefix, prefix, options)
+    update_resources_access_mode(access_mode, :prefix, prefix, options)
   end
 
-  # Update resources access mode. Resources are selected by the tag
-  # @param [String] access_mode the access mode to set the resources to
-  # @param [String] tag the tag by which to filter applicable resources
-  # @param [Object] options    additional options
-  # @option options [String] :resource_type ("image") the type of resources to modify
-  # @option options [Fixnum] :max_results (nil) the maximum resources to process in a single invocation
-  # @option options [String] :next_cursor (nil) provided by a previous call to the method
+  # Update resources access mode. Resources are selected by the tag.
+  #
+  # @param [String] access_mode The access mode to set the resources to.
+  # @param [String] tag         The tag by which to filter applicable resources.
+  # @param [Hash]   options     The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#examples-8
   def self.update_resources_access_mode_by_tag(access_mode, tag, options = {})
-
-      update_resources_access_mode(access_mode, :tag, tag, options)
+    update_resources_access_mode(access_mode, :tag, tag, options)
   end
 
-  # Update resources access mode. Resources are selected by the provided public_ids
-  # @param [String] access_mode the access mode to set the resources to
-  # @param [Array<String>] public_ids The prefix by which to filter applicable resources
-  # @param [Object] options    additional options
-  # @option options [String] :resource_type ("image") the type of resources to modify
-  # @option options [Fixnum] :max_results (nil) the maximum resources to process in a single invocation
-  # @option options [String] :next_cursor (nil) provided by a previous call to the method
+  # Update resources access mode. Resources are selected by the provided public_ids.
+  #
+  # @param [String] access_mode The access mode to set the resources to.
+  # @param [Array] public_ids   The ids by which to filter applicable resources
+  # @param [Hash] options       The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#examples-8
   def self.update_resources_access_mode_by_ids(access_mode, public_ids, options = {})
-
-      update_resources_access_mode(access_mode, :public_ids, public_ids, options)
+    update_resources_access_mode(access_mode, :public_ids, public_ids, options)
   end
 
+  # Gets the breakpoints.
+  #
+  # Returns breakpoints if defined, otherwise checks the cache(if configured), otherwise fall backs to static
+  # calculation.
+  #
+  # @param [String] public_id Resource source.
+  # @param [Hash]   options   The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @internal
   def self.get_breakpoints(public_id, options)
     local_options = options.clone
     base_transformation = Cloudinary::Utils.generate_transformation_string(local_options)
     srcset = local_options[:srcset]
     breakpoints = [:min_width, :max_width, :bytes_step, :max_images].map {|k| srcset[k]}.join('_')
 
-
     local_options[:transformation] = [base_transformation, width: "auto:breakpoints_#{breakpoints}:json"]
     json_url = Cloudinary::Utils.cloudinary_url public_id, local_options
     call_json_api('GET', json_url, {}, 60, {})
   end
 
-  # Returns a list of all metadata field definitions.
+  # Lists all metadata field definitions.
   #
-  # @see https://cloudinary.com/documentation/admin_api#get_metadata_fields Get metadata fields API reference
+  # @param [Hash] options The optional parameters.
   #
-  # @param [Hash] options Additional options
   # @return [Cloudinary::Api::Response]
+  #
   # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_metadata_fields
   def self.list_metadata_fields(options = {})
     call_metadata_api(:get, [], {}, options)
   end
 
-  # Gets a metadata field by external id.
+  # Gets a single metadata field definition by external ID.
   #
-  # @see https://cloudinary.com/documentation/admin_api#get_a_metadata_field_by_external_id Get metadata field by external ID API reference
+  # @param [String] field_external_id The external ID of the field to retrieve.
+  # @param [Hash]   options           The optional parameters.
   #
-  # @param [String] field_external_id The ID of the metadata field to retrieve
-  # @param [Hash]   options           Additional options
   # @return [Cloudinary::Api::Response]
+  #
   # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_a_metadata_field_by_external_id
   def self.metadata_field_by_field_id(field_external_id, options = {})
     uri = [field_external_id]
 
@@ -367,31 +898,33 @@ class Cloudinary::Api
 
   # Creates a new metadata field definition.
   #
-  # @see https://cloudinary.com/documentation/admin_api#create_a_metadata_field Create metadata field API reference
+  # @param [Hash] field   The field to add.
+  # @param [Hash] options The optional parameters.
   #
-  # @param [Hash] field   The field to add
-  # @param [Hash] options Additional options
   # @return [Cloudinary::Api::Response]
+  #
   # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#create_a_metadata_field
   def self.add_metadata_field(field, options = {})
     params = only(field, :type, :external_id, :label, :mandatory, :default_value, :validation, :datasource)
 
     call_metadata_api(:post, [], params, options)
   end
 
-  # Updates a metadata field by external id.
+  # Updates a metadata field by external ID.
   #
   # Updates a metadata field definition (partially, no need to pass the entire object) passed as JSON data.
-  # See https://cloudinary.com/documentation/admin_api#generic_structure_of_a_metadata_field for the generic structure
-  # of a metadata field.
   #
-  # @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_by_external_id Update metadata field API reference
+  # @param [String] field_external_id The ID of the field to update.
+  # @param [Hash]   field             The field definition.
+  # @param [Hash]   options           The optional parameters.
   #
-  # @param [String] field_external_id The id of the metadata field to update
-  # @param [Hash]   field             The field definition
-  # @param [Hash]   options           Additional options
   # @return [Cloudinary::Api::Response]
+  #
   # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_by_external_id
   def self.update_metadata_field(field_external_id, field, options = {})
     uri = [field_external_id]
     params = only(field, :label, :mandatory, :default_value, :validation)
@@ -399,35 +932,40 @@ class Cloudinary::Api
     call_metadata_api(:put, uri, params, options)
   end
 
-  # Deletes a metadata field definition.
+  # Deletes a metadata field definition by external ID.
   #
-  # The field should no longer be considered a valid candidate for all other endpoints.
+  # The external ID is immutable. Therefore, once deleted, the field's external ID can no longer be used for
+  # future purposes.
   #
-  # @see https://cloudinary.com/documentation/admin_api#delete_a_metadata_field_by_external_id Delete metadata field API reference
+  # @param [String] field_external_id The ID of the field to delete.
+  # @param [Hash]   options           The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
   #
-  # @param [String] field_external_id The external id of the field to delete
-  # @param [Hash]   options           Additional options
-  # @return [Cloudinary::Api::Response] A hash with a "message" key. "ok" value indicates a successful deletion
   # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_a_metadata_field_by_external_id
   def self.delete_metadata_field(field_external_id, options = {})
     uri = [field_external_id]
 
     call_metadata_api(:delete, uri, {}, options)
   end
 
-  # Deletes entries in a metadata field datasource.
+  # Deletes entries in a metadata single or multi-select field's datasource.
   #
-  # Deletes (blocks) the datasource entries for a specified metadata field definition. Sets the state of the
-  # entries to inactive. This is a soft delete, the entries still exist under the hood and can be activated
-  # again with the restore datasource entries method.
+  # Deletes (blocks) the datasource (list) entries from the specified metadata field definition. Sets the state of
+  # the entries to inactive. This is a soft delete. The entries still exist in the database and can be reactivated
+  # using the restoreDatasourceEntries method.
   #
-  # @see https://cloudinary.com/documentation/admin_api#delete_entries_in_a_metadata_field_datasource Delete entries in a metadata field datasource API reference
+  # @param [String] field_external_id    The ID of the field to update.
+  # @param [Array]  entries_external_id  The IDs of the entries to delete from the data source.
+  # @param [Hash]   options              The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
   #
-  # @param [String] field_external_id    The id of the field to update
-  # @param [Array]  entries_external_id  The ids of all the entries to delete from the datasource
-  # @param [Hash]   options              Additional options
-  # @return [Cloudinary::Api::Response] The remaining datasource entries
   # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_entries_in_a_metadata_field_datasource
   def self.delete_datasource_entries(field_external_id, entries_external_id, options = {})
     uri = [field_external_id, "datasource"]
     params = {:external_ids => entries_external_id }
@@ -437,17 +975,20 @@ class Cloudinary::Api
 
   # Updates a metadata field datasource.
   #
-  # Updates the datasource of a supported field type (currently only enum and set), passed as JSON data. The
+  # Updates the datasource of a supported field type (currently enum or set), passed as JSON data. The
   # update is partial: datasource entries with an existing external_id will be updated and entries with new
   # external_id’s (or without external_id’s) will be appended.
   #
-  # @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_datasource Update a metadata field datasource API reference
+  # @param [String] field_external_id   The ID of the field to update.
+  # @param [Array]  entries_external_id A list of datasource entries. Existing entries (according to entry id) will be
+  #                                     updated. New entries will be added.
+  # @param [Hash]   options             The optional parameters.
   #
-  # @param [String] field_external_id   The external id of the field to update
-  # @param [Array]  entries_external_id
-  # @param [Hash]   options             Additional options
   # @return [Cloudinary::Api::Response]
+  #
   # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_datasource
   def self.update_metadata_field_datasource(field_external_id, entries_external_id, options = {})
     uri = [field_external_id, "datasource"]
 
@@ -459,18 +1000,20 @@ class Cloudinary::Api
     call_metadata_api(:put, uri, params, options)
   end
 
-  # Restores entries in a metadata field datasource.
+  # Restore entries in a metadata field datasource.
   #
   # Restores (unblocks) any previously deleted datasource entries for a specified metadata field definition.
   # Sets the state of the entries to active.
   #
-  # @see https://cloudinary.com/documentation/admin_api#restore_entries_in_a_metadata_field_datasource Restore entries in a metadata field datasource API reference
+  # @param [String] field_external_id    The ID of the metadata field.
+  # @param [Array]  entries_external_ids An array of IDs of datasource entries to restore (unblock).
+  # @param [Hash]   options              The optional parameters.
   #
-  # @param [String] field_external_id    The ID of the metadata field
-  # @param [Array]  entries_external_ids An array of IDs of datasource entries to restore (unblock)
-  # @param [Hash]   options              Additional options
   # @return [Cloudinary::Api::Response]
+  #
   # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/admin_api#restore_entries_in_a_metadata_field_datasource
   def self.restore_metadata_field_datasource(field_external_id, entries_external_ids, options = {})
     uri = [field_external_id, "datasource_restore"]
     params = {:external_ids => entries_external_ids }
@@ -478,18 +1021,67 @@ class Cloudinary::Api
     call_metadata_api(:post, uri, params, options)
   end
 
+  # Reorders metadata field datasource. Currently supports only value.
+  #
+  # @param [String] field_external_id The ID of the metadata field
+  # @param [String] order_by          Criteria for the order. Currently supports only value
+  # @param [String] direction         Optional (gets either asc or desc)
+  # @param [Hash]   options           Configuration options
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  def self.reorder_metadata_field_datasource(field_external_id, order_by, direction = nil, options = {})
+    uri    = [field_external_id, "datasource", "order"]
+    params = { :order_by => order_by, :direction => direction }
+
+    call_metadata_api(:post, uri, params, options)
+  end
+
+  # Reorders metadata fields.
+  #
+  # @param [String] order_by  Criteria for the order (one of the fields 'label', 'external_id', 'created_at').
+  # @param [String] direction Optional (gets either asc or desc).
+  # @param [Hash]   options   Configuration options.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  def self.reorder_metadata_fields(order_by, direction = nil, options = {})
+    uri    = ["order"]
+    params = { :order_by => order_by, :direction => direction }
+
+    call_metadata_api(:put, uri, params, options)
+  end
+
   protected
 
+  # Execute a call api for input params.
+  # @param [Object] method The method for a request
+  # @param [Object] uri The uri for a request
+  # @param [Object] params Additional params
+  # @param [Object] options Additional options
+  # @return [Cloudinary::Api::Response] Returned response from Cloudinary
+  # @raise [Cloudinary::Api::Error]
   def self.call_api(method, uri, params, options)
-    cloud_name = options[:cloud_name] || Cloudinary.config.cloud_name || raise('Must supply cloud_name')
-    api_key    = options[:api_key] || Cloudinary.config.api_key || raise('Must supply api_key')
-    api_secret = options[:api_secret] || Cloudinary.config.api_secret || raise('Must supply api_secret')
+    cloud_name  = options[:cloud_name] || Cloudinary.config.cloud_name || raise('Must supply cloud_name')
+    api_key     = options[:api_key] || Cloudinary.config.api_key
+    api_secret  = options[:api_secret] || Cloudinary.config.api_secret
+    oauth_token = options[:oauth_token] || Cloudinary.config.oauth_token
+
+    validate_authorization(api_key, api_secret, oauth_token)
+
+    auth = { :key => api_key, :secret => api_secret, :oauth_token => oauth_token }
 
-    call_cloudinary_api(method, uri, api_key, api_secret, params, options) do |cloudinary, inner_uri|
+    call_cloudinary_api(method, uri, auth, params, options) do |cloudinary, inner_uri|
       [cloudinary, 'v1_1', cloud_name, inner_uri]
     end
   end
 
+  # Parse a json response.
+  # @param [Object] response Returned response from Cloudinary
+  # @return [Hash] Decoded string
+  # @raise [Cloudinary::Api::GeneralError]
   def self.parse_json_response(response)
     return Cloudinary::Utils.json_decode(response.body)
   rescue => e
@@ -504,7 +1096,7 @@ class Cloudinary::Api
   # @param [Array]  uri     REST endpoint of the API (without 'metadata_fields')
   # @param [Hash]   params  Query/body parameters passed to the method
   # @param [Hash]   options Additional options. Can be an override of the configuration, headers, etc.
-  # @return [Cloudinary::Api::Response]
+  # @return [Cloudinary::Api::Response] Returned response from Cloudinary
   # @raise [Cloudinary::Api::Error]
   def self.call_metadata_api(method, uri, params, options)
     options[:content_type] = :json
@@ -513,6 +1105,31 @@ class Cloudinary::Api
     call_api(method, uri, params, options)
   end
 
+  # Prepares optional parameters for asset/assetByAssetId API calls.
+  # @param  [Hash]   options Additional options
+  # @return [Object]         Optional parameters
+  def self.prepare_resource_details_params(options)
+    only(options,
+         :exif,
+         :colors,
+         :faces,
+         :quality_analysis,
+         :image_metadata,
+         :phash,
+         :pages,
+         :cinemagraph_analysis,
+         :coordinates,
+         :max_results,
+         :derived_next_cursor,
+         :accessibility_analysis,
+         :versions
+    )
+  end
+
+  # Filter hash with specific keys.
+  # @param [Object] hash Input hash
+  # @param [Array] keys Input keys
+  # @return [Hash] Result of hash filtering
   def self.only(hash, *keys)
     result = {}
     keys.each do |key|
@@ -522,32 +1139,65 @@ class Cloudinary::Api
     result
   end
 
+  # Merge params with a certain set of options.
+  # @param [Object] options Set of options
+  # @param [Hash] params Additional params
+  # @return [Hash] Result of hash merging
   def self.delete_resource_params(options, params ={})
     params.merge(only(options, :keep_original, :next_cursor, :invalidate, :transformations))
   end
 
+  # Generate a transformation string if an input a param is not a string.
+  # @param [String|Hash] transformation Input transformation param
+  # @return [String] Result of transformation
   def self.transformation_string(transformation)
     transformation.is_a?(String) ? transformation : Cloudinary::Utils.generate_transformation_string(transformation.clone)
   end
 
+  # Publish resources.
+  # @param [Hash] options Additional options
+  # @return [Cloudinary::Api::Response] Returned response from Cloudinary
+  # @raise [Cloudinary::Api::Error]
   def self.publish_resources(options = {})
     resource_type = options[:resource_type] || "image"
     params = only(options, :public_ids, :prefix, :tag, :type, :overwrite, :invalidate)
     call_api("post", "resources/#{resource_type}/publish_resources", params, options)
   end
 
+  # Publish resources by a prefix.
+  # @param [String] prefix The name of a prefix
+  # @param [Hash] options Additional options
+  # @return [Cloudinary::Api::Response] Returned response from Cloudinary
+  # @raise [Cloudinary::Api::Error]
   def self.publish_by_prefix(prefix, options = {})
     return self.publish_resources(options.merge(:prefix => prefix))
   end
 
+  # Publish resources by a tag.
+  # @param [String] tag The name of a tag
+  # @param [Hash] options Additional options
+  # @return [Cloudinary::Api::Response] Returned response from Cloudinary
+  # @raise [Cloudinary::Api::Error]
   def self.publish_by_tag(tag, options = {})
     return self.publish_resources(options.merge(:tag => tag))
   end
 
+  # Publish resources by ids.
+  # @param [Array] publicIds List of public ids
+  # @param [Hash] options Additional options
+  # @return [Cloudinary::Api::Response] Returned response from Cloudinary
+  # @raise [Cloudinary::Api::Error]
   def self.publish_by_ids(publicIds, options = {})
     return self.publish_resources(options.merge(:public_ids => publicIds))
   end
 
+  # Build a link and prepare data for a call.
+  # @param [String] access_mode The access_mode of resources
+  # @param [Symbol] by_key The new access mode to be set. Possible values: public, authenticated.
+  # @param [String|Array<String>] value The value to assign
+  # @param [Hash] options Additional options
+  # @return [Cloudinary::Api::Response] Returned response from Cloudinary
+  # @raise [Cloudinary::Api::Error]
   def self.update_resources_access_mode(access_mode, by_key, value, options = {})
     resource_type = options[:resource_type] || "image"
     type = options[:type] || "upload"