nexosis_api 2.0.0 → 2.0.1

data/lib/nexosis_api/client/datasets.rb

@@ -1,155 +1,155 @@
-require 'csv'
-
-module NexosisApi
-  class Client
-    # Dataset-based API operations
-    #
-    # @see http://docs.nexosis.com/
-    module Datasets
-      # save data in a named dataset
-      #
-      # @param dataset_name [String] name to save the dataset
-      # @param json_data [Hash] parsed json data
-      # @return [NexosisApi::DatasetSummary] information about your upload
-      # @note input json is to be a hash, do not send a json string via to_json.
-      def create_dataset_json(dataset_name, json_data)
-        create_dataset dataset_name, json_data.to_json, 'application/json'
-      end
-
-      # save data in a named dataset from csv content
-      #
-      # @param dataset_name [String] name to save the dataset
-      # @param csv [CSV] csv content ready for reading
-      # @return [NexosisApi::DatasetSummary] information about your upload
-      def create_dataset_csv(dataset_name, csv)
-        content = process_csv_to_s csv
-        create_dataset dataset_name, content, 'text/csv'
-      end
-
-      # Gets the list of data sets that have been saved to the system, optionally filtering by partial name match.
-      #
-      # @param partial_name [String] if provided, all datasets returned will contain this string
-      # @param page [int] page number for items in list
-      # @param page_size [int] number of items in each page
-      # @return [NexosisApi::PagedArray of NexosisApi::DatasetSummary] array of datasets found
-      # @since 1.4 - added paging parameters
-      def list_datasets(partial_name = '', page = 0, page_size = 50)
-        list_dataset_url = '/data'
-        query = {
-          page: page,
-          pageSize: page_size
-        }
-        query['partialName'] = partial_name unless partial_name.empty?
-        response = self.class.get(list_dataset_url, headers: @headers, query: query)
-        if response.success?
-          NexosisApi::PagedArray.new(response.parsed_response,
-                                     response.parsed_response['items']
-                                     .map { |dr| NexosisApi::DatasetSummary.new(dr) })
-        else
-          raise HttpException.new("There was a problem listing datasets: #{response.code}.", "listing datasets with partial name #{partial_name}", response)
-        end
-      end
-
-      # Get the data in the set, with paging, and optional projection.
-      #
-      # @param dataset_name [String] name of the dataset for which to retrieve data.
-      # @param page_number [Integer] zero-based page number of results to retrieve
-      # @param page_size [Integer] Count of results to retrieve in each page (max 1000).
-      # @param query_options [Hash] options hash for limiting and projecting returned results
-      # @note Query Options includes start_date as a DateTime or ISO 8601 compliant string,
-      #    end_date, also as a DateTime or string, and :include as an Array of strings indicating the columns to return.
-      #    The dates can be used independently and are inclusive. Lack of options returns all values within the given page.
-      def get_dataset(dataset_name, page_number = 0, page_size = 50, query_options = {})
-        response = get_dataset_internal(dataset_name, page_number, page_size, query_options)
-        return NexosisApi::DatasetData.new(response.parsed_response) if response.success?
-        raise HttpException.new("There was a problem getting the dataset: #{response.code}.", "getting dataset #{dataset_name}", response)
-      end
-
-      # Get the data in the set, written to a CSV file, optionally filtering it.
-      #
-      # @param dataset_name [String] name of the dataset for which to retrieve data.
-      # @param page_number [Integer] zero-based page number of results to retrieve
-      # @param page_size [Integer] Count of results to retrieve in each page (max 1000).
-      # @param query_options [Hash] options hash for limiting and projecting returned results
-      # @note Query Options includes start_date as a DateTime or ISO 8601 compliant string,
-      #    end_date, also as a DateTime or string, and :include as an Array of strings indicating the columns to return.
-      #    The dates can be used independently and are inclusive. Lack of options returns all values within the given page.
-      # @example get page 1 with 20 results each page
-      #    NexosisApi.client.get_dataset_csv('MyDataset', 1, 20, {:include => 'sales'})
-      def get_dataset_csv(dataset_name, page_number = 0, page_size = 50, query_options = {})
-        response = get_dataset_internal(dataset_name, page_number, page_size, query_options, 'text/csv')
-        return response.body if response.success?
-        raise HttpException.new("There was a problem getting the dataset: #{response.code}.", "getting dataset #{dataset_name}", response)
-      end
-
-      # Remove data from a data set or the entire set.
-      #
-      # @param dataset_name [String] the name of the dataset from which to remove data
-      # @param filter_options [Hash] filtering which data to remove
-      # @note Options: start_date, end_date, cascade_forecast, cascade_sessions, cascade
-      #    - start_date - the first date on which to start removing data
-      #    - end_date - the last date on which to finish removing data
-      #    - cascade_forecast - will cascade deletes to all related forecasts
-      #    - cascade_session - will cascade deletes to all related sessions
-      #    - cascade_view - will cascade deletes to all related views (any part of join - think twice)
-      #    - cascase_model - will cascade deletes to all models created from this dataset
-      #    - cascade - will cascade deletes to all related forecasts and sessions
-      # @example - request delete with cascade forecast
-      #    NexosisApi.client.remove_dataset('mydataset', {:cascade_forecast => true})
-      def remove_dataset(dataset_name, filter_options = {})
-        raise ArgumentError, 'dataset_name was not provided and is not optional ' if dataset_name.to_s.empty?
-        dataset_remove_url = "/data/#{dataset_name}"
-        query = {}
-        if filter_options.empty? == false
-          cascade_query = create_cascade_options(filter_options)
-          query['cascade'] = cascade_query unless cascade_query.nil?
-          query['startDate'] = [filter_options[:start_date].to_s] unless filter_options[:start_date].nil?
-          query['endDate'] = [filter_options[:end_date].to_s] unless filter_options[:end_date].nil?
-        end
-        # normalizer = proc { |query_set| query_set.map { |key, value| value.map { |v| "#{key}=#{v}" } }.join('&') }
-        response = self.class.delete(dataset_remove_url,
-                                     headers: @headers,
-                                     query: query,
-                                     query_string_normalizer: ->(query_map) {array_query_normalizer(query_map)})
-        return if response.success?
-        raise HttpException.new("There was a problem removing the dataset: #{response.code}.", "removing dataset #{dataset_name}", response)
-      end
-
-      private
-
-      # @private
-      def create_dataset(dataset_name, content, content_type)
-        raise ArgumentError, 'dataset_name was not provided and is not optional ' if dataset_name.to_s.empty?
-        dataset_url = "/data/#{dataset_name}"
-        headers = { 'api-key' => @api_key, 'Content-Type' => content_type }
-        response = self.class.put(dataset_url, headers: headers, body: content)
-        if response.success?
-          NexosisApi::DatasetSummary.new(response)
-        else
-          raise HttpException.new("There was a problem uploading the dataset: #{response.code}.", "uploading dataset #{dataset_name}", response)
-        end
-      end
-
-      # @private
-      def get_dataset_internal(dataset_name, page_number = 0, page_size = 50, query_options = {}, content_type = 'application/json')
-        raise ArgumentError, 'page size must be <= 1000 items per page' unless page_size <= 1000
-        raise ArgumentError, 'dataset_name was not provided and is not optional' unless dataset_name.to_s.empty? == false
-        dataset_url = "/data/#{dataset_name}"
-        headers = { 'api-key' => @api_key, 'Accept' => content_type }
-        self.class.get(dataset_url, headers: headers,
-                                    query: create_query(page_number, page_size, query_options),
-                                    query_string_normalizer: ->(query_map) { array_query_normalizer(query_map) })
-      end
-
-      # @private
-      def create_cascade_options(option_hash)
-        return nil if option_hash.nil?
-        return %w[session view forecast model] if option_hash.key?(:cascade)
-        options_set = []
-        option_hash.each_key { |k| options_set << k.to_s.gsub(/cascade_/, '') if k.to_s.include? 'cascade_' }
-        # HACK: required to be backward compatible with incorrect key names
-        options_set.map { |s| s.chomp('s') }
-      end
-    end
-  end
-end
+require 'csv'
+
+module NexosisApi
+  class Client
+    # Dataset-based API operations
+    #
+    # @see http://docs.nexosis.com/
+    module Datasets
+      # save data in a named dataset
+      #
+      # @param dataset_name [String] name to save the dataset
+      # @param json_data [Hash] parsed json data
+      # @return [NexosisApi::DatasetSummary] information about your upload
+      # @note input json is to be a hash, do not send a json string via to_json.
+      def create_dataset_json(dataset_name, json_data)
+        create_dataset dataset_name, json_data.to_json, 'application/json'
+      end
+
+      # save data in a named dataset from csv content
+      #
+      # @param dataset_name [String] name to save the dataset
+      # @param csv [CSV] csv content ready for reading
+      # @return [NexosisApi::DatasetSummary] information about your upload
+      def create_dataset_csv(dataset_name, csv)
+        content = process_csv_to_s csv
+        create_dataset dataset_name, content, 'text/csv'
+      end
+
+      # Gets the list of data sets that have been saved to the system, optionally filtering by partial name match.
+      #
+      # @param partial_name [String] if provided, all datasets returned will contain this string
+      # @param page [int] page number for items in list
+      # @param page_size [int] number of items in each page
+      # @return [NexosisApi::PagedArray of NexosisApi::DatasetSummary] array of datasets found
+      # @since 1.4 - added paging parameters
+      def list_datasets(partial_name = '', page = 0, page_size = 50)
+        list_dataset_url = '/data'
+        query = {
+          page: page,
+          pageSize: page_size
+        }
+        query['partialName'] = partial_name unless partial_name.empty?
+        response = self.class.get(list_dataset_url, headers: @headers, query: query)
+        if response.success?
+          NexosisApi::PagedArray.new(response.parsed_response,
+                                     response.parsed_response['items']
+                                     .map { |dr| NexosisApi::DatasetSummary.new(dr) })
+        else
+          raise HttpException.new("There was a problem listing datasets: #{response.code}.", "listing datasets with partial name #{partial_name}", response)
+        end
+      end
+
+      # Get the data in the set, with paging, and optional projection.
+      #
+      # @param dataset_name [String] name of the dataset for which to retrieve data.
+      # @param page_number [Integer] zero-based page number of results to retrieve
+      # @param page_size [Integer] Count of results to retrieve in each page (max 1000).
+      # @param query_options [Hash] options hash for limiting and projecting returned results
+      # @note Query Options includes start_date as a DateTime or ISO 8601 compliant string,
+      #    end_date, also as a DateTime or string, and :include as an Array of strings indicating the columns to return.
+      #    The dates can be used independently and are inclusive. Lack of options returns all values within the given page.
+      def get_dataset(dataset_name, page_number = 0, page_size = 50, query_options = {})
+        response = get_dataset_internal(dataset_name, page_number, page_size, query_options)
+        return NexosisApi::DatasetData.new(response.parsed_response) if response.success?
+        raise HttpException.new("There was a problem getting the dataset: #{response.code}.", "getting dataset #{dataset_name}", response)
+      end
+
+      # Get the data in the set, written to a CSV file, optionally filtering it.
+      #
+      # @param dataset_name [String] name of the dataset for which to retrieve data.
+      # @param page_number [Integer] zero-based page number of results to retrieve
+      # @param page_size [Integer] Count of results to retrieve in each page (max 1000).
+      # @param query_options [Hash] options hash for limiting and projecting returned results
+      # @note Query Options includes start_date as a DateTime or ISO 8601 compliant string,
+      #    end_date, also as a DateTime or string, and :include as an Array of strings indicating the columns to return.
+      #    The dates can be used independently and are inclusive. Lack of options returns all values within the given page.
+      # @example get page 1 with 20 results each page
+      #    NexosisApi.client.get_dataset_csv('MyDataset', 1, 20, {:include => 'sales'})
+      def get_dataset_csv(dataset_name, page_number = 0, page_size = 50, query_options = {})
+        response = get_dataset_internal(dataset_name, page_number, page_size, query_options, 'text/csv')
+        return response.body if response.success?
+        raise HttpException.new("There was a problem getting the dataset: #{response.code}.", "getting dataset #{dataset_name}", response)
+      end
+
+      # Remove data from a data set or the entire set.
+      #
+      # @param dataset_name [String] the name of the dataset from which to remove data
+      # @param filter_options [Hash] filtering which data to remove
+      # @note Options: start_date, end_date, cascade_forecast, cascade_sessions, cascade
+      #    - start_date - the first date on which to start removing data
+      #    - end_date - the last date on which to finish removing data
+      #    - cascade_forecast - will cascade deletes to all related forecasts
+      #    - cascade_session - will cascade deletes to all related sessions
+      #    - cascade_view - will cascade deletes to all related views (any part of join - think twice)
+      #    - cascase_model - will cascade deletes to all models created from this dataset
+      #    - cascade - will cascade deletes to all related forecasts and sessions
+      # @example - request delete with cascade forecast
+      #    NexosisApi.client.remove_dataset('mydataset', {:cascade_forecast => true})
+      def remove_dataset(dataset_name, filter_options = {})
+        raise ArgumentError, 'dataset_name was not provided and is not optional ' if dataset_name.to_s.empty?
+        dataset_remove_url = "/data/#{dataset_name}"
+        query = {}
+        if filter_options.empty? == false
+          cascade_query = create_cascade_options(filter_options)
+          query['cascade'] = cascade_query unless cascade_query.nil?
+          query['startDate'] = [filter_options[:start_date].to_s] unless filter_options[:start_date].nil?
+          query['endDate'] = [filter_options[:end_date].to_s] unless filter_options[:end_date].nil?
+        end
+        # normalizer = proc { |query_set| query_set.map { |key, value| value.map { |v| "#{key}=#{v}" } }.join('&') }
+        response = self.class.delete(dataset_remove_url,
+                                     headers: @headers,
+                                     query: query,
+                                     query_string_normalizer: ->(query_map) {array_query_normalizer(query_map)})
+        return if response.success?
+        raise HttpException.new("There was a problem removing the dataset: #{response.code}.", "removing dataset #{dataset_name}", response)
+      end
+
+      private
+
+      # @private
+      def create_dataset(dataset_name, content, content_type)
+        raise ArgumentError, 'dataset_name was not provided and is not optional ' if dataset_name.to_s.empty?
+        dataset_url = "/data/#{dataset_name}"
+        headers = { 'api-key' => @api_key, 'Content-Type' => content_type }
+        response = self.class.put(dataset_url, headers: headers, body: content)
+        if response.success?
+          NexosisApi::DatasetSummary.new(response)
+        else
+          raise HttpException.new("There was a problem uploading the dataset: #{response.code}.", "uploading dataset #{dataset_name}", response)
+        end
+      end
+
+      # @private
+      def get_dataset_internal(dataset_name, page_number = 0, page_size = 50, query_options = {}, content_type = 'application/json')
+        raise ArgumentError, 'page size must be <= 1000 items per page' unless page_size <= 1000
+        raise ArgumentError, 'dataset_name was not provided and is not optional' unless dataset_name.to_s.empty? == false
+        dataset_url = "/data/#{dataset_name}"
+        headers = { 'api-key' => @api_key, 'Accept' => content_type }
+        self.class.get(dataset_url, headers: headers,
+                                    query: create_query(page_number, page_size, query_options),
+                                    query_string_normalizer: ->(query_map) { array_query_normalizer(query_map) })
+      end
+
+      # @private
+      def create_cascade_options(option_hash)
+        return nil if option_hash.nil?
+        return %w[session view forecast model] if option_hash.key?(:cascade)
+        options_set = []
+        option_hash.each_key { |k| options_set << k.to_s.gsub(/cascade_/, '') if k.to_s.include? 'cascade_' }
+        # HACK: required to be backward compatible with incorrect key names
+        options_set.map { |s| s.chomp('s') }
+      end
+    end
+  end
+end

data/lib/nexosis_api/client/imports.rb

@@ -1,141 +1,141 @@
-require 'json'
-module NexosisApi
-  class Client
-    # Imports-based API operations
-    #
-    # @see http://docs.nexosis.com/
-    module Imports
-
-      # List all existing import requests
-      #
-      # @param dataset_name [String] optional name filter of dataset which was imported
-      # @param page [int] page number for items in list
-      # @param page_size [int] number of items in each page
-      # @return [NexosisApi::PagedArray of NexosisApi::ImportsResponse]
-      # @since 1.4 added paging parameters
-      def list_imports(dataset_name = '', page = 0, page_size = 50)
-        imports_url = '/imports'
-        query = {
-          dataSetName: dataset_name,
-          page: page,
-          pageSize: page_size
-        }
-        response = self.class.get(imports_url, headers: @headers, query: query)
-        if (response.success?)
-          NexosisApi::PagedArray.new(response.parsed_response,
-                                     response.parsed_response['items']
-                                     .map { |i| NexosisApi::ImportsResponse.new(i) })
-        else
-          raise HttpException.new("There was a problem getting the imports: #{response.code}.", "uploading dataset from s3 #{dataset_name}", response)
-        end
-      end
-
-      # Import a file from AWS s3 as your dataset
-      #
-      # @param dataset_name [String] the name to give to the new dataset or existing dataset to which this data will be upserted
-      # @param bucket_name [String] the AWS S3 bucket name in which the path will be found
-      # @param path [String] the path within the bucket (usually file name)
-      # @param region [String] the region in which your bucket exists. Defaults to us-east-1
-      # @param credentials [Hash] :access_key_id and :secret_access_key for user with rights to read the target file.
-      # @param column_metadata [Array of NexosisApi::Column] description of each column in target dataset. Optional.
-      # @return [NexosisApi::ImportsResponse]
-      # @see http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region for information on region names
-      # @note If credentials are provided they will be encrypted at the server, used once, and then removed from storage.
-      def import_from_s3(dataset_name, bucket_name, path, region = 'us-east-1', credentials = {}, column_metadata = [])
-        raise ArgumentError, 'dataset_name was not provided and is not optional ' unless dataset_name.to_s.empty? == false
-        raise ArgumentError, 'bucket_name was not provided and is not optional ' unless bucket_name.to_s.empty? == false
-        raise ArgumentError, 'path was not provided and is not optional ' unless path.to_s.empty? == false
-        s3_import_url = '/imports/s3'
-        column_json = Column.to_json(column_metadata)
-        body = {
-          'dataSetName' => dataset_name,
-          'bucket' => bucket_name,
-          'path' => path,
-          'region' => region,
-          'columns' => column_json
-        }
-        body['accessKeyId'] = credentials[:access_key_id] unless credentials.nil? || credentials[:access_key_id].nil?
-        body['secretAccessKey'] = credentials[:secret_access_key] unless credentials.nil? || credentials[:secret_access_key].nil?
-        response = self.class.post(s3_import_url, headers: @headers, body: body.to_json)
-        raise HttpException.new("There was a problem importing from s3: #{response.code}.",
-                                "uploading dataset from s3 #{dataset_name}",
-                                response) unless response.success?
-        NexosisApi::ImportsResponse.new(response.parsed_response)
-      end
-
-      # Get response back from import created previously. Presumably to check status.
-      #
-      # @param import_id [String] The id returned from a previous request to import
-      # @return [NexosisApi::ImportsResponse]
-      # @example get import
-      #    NexosisApi.client.retrieve_import('740dca2a-b488-4322-887e-fa473b1caa54')
-      def retrieve_import(import_id)
-        raise ArgumentError, 'import_id was not provided and is not optional ' unless import_id.to_s.empty? == false
-        imports_url = "/imports/#{import_id}"
-        response = self.class.get(imports_url, headers: @headers)
-        raise HttpException.new("There was a problem getting the import #{response.code}.",
-                                "requesting an import #{import_id}", response) unless response.success?
-        NexosisApi::ImportsResponse.new(response.parsed_response)
-      end
-
-      # Import a csv, json file (gzip'd or raw) from a Microsoft Azure storage blob
-      #
-      # @param dataset_name [String] the name to give to the new dataset or existing dataset to which this data will be upserted
-      # @param connection_string [String] the azure blob storage connection string providing access to the file resource
-      # @param container [String] the container in which the object is located.
-      # @param blob_name [String] the name of the object to import, usually a file. Always csv or json content.
-      # If folders have been used this will contain the full path within the container.
-      # @param column_metadata [Array of NexosisApi::Column] description of each column in target dataset. Optional.
-      # @return [NexosisApi::ImportsResponse]
-      # @since 2.0.0
-      # @note the connection string provided will be encrypted at the server, used once, and then removed from storage.
-      def import_from_azure(dataset_name, connection_string, container, blob_name, column_metadata = [])
-        raise ArgumentError, 'dataset_name was not provided and is not optional ' unless dataset_name.empty? == false
-        raise ArgumentError, 'connection_string was not provided and is not optional ' unless connection_string.empty? == false
-        raise ArgumentError, 'container was not provided and is not optional ' unless container.empty? == false
-        raise ArgumentError, 'blob_name was not provided and is not optional ' unless blob_name.empty? == false
-        azure_url = '/imports/azure'
-        column_json = Column.to_json(column_metadata)
-        body = {
-          'dataSetName' => dataset_name,
-          'connectionString' => connection_string,
-          'container' => container,
-          'blob' => blob_name,
-          'columns' => column_json
-        }
-        response = self.class.post(azure_url, headers: @headers, body: body.to_json)
-        raise HttpException.new("There was a problem importing from azure: #{response.code}.",
-                                "uploading dataset from azure #{dataset_name}",
-                                response) unless response.success?
-        NexosisApi::ImportsResponse.new(response.parsed_response)
-      end
-
-      # Import a csv or json file directly from any avaiable and reachable public endpoint.
-      #
-      # @param dataset_name [String] the name to give to the new dataset or existing dataset to which this data will be upserted
-      # @param url [String] the url indicating where to find the file resource to import
-      # @param column_metadata [Array of NexosisApi::Column] description of each column in target dataset. Optional.
-      # @param options [Hash] may provide basic auth credentials or a 'content-type' value to identify csv or json content.
-      # @return [NexosisApi::ImportsResponse]
-      # @note imports depend on file extensions, so use a content type indicator if json or csv cannot be inferred.
-      # @note Urls protected by basic auth can be accessed if given a userid and password in options
-      # @since 2.0.0
-      def import_from_url(dataset_name, url, column_metadata = [], options = {})
-        raise ArgumentError, 'dataset_name was not provided and is not optional ' unless dataset_name.empty? == false
-        raise ArgumentError, 'url was not provided and is not optional ' unless url.empty? == false
-        endpoint_url = '/imports/url'
-        column_json = Column.to_json(column_metadata)
-        body = {
-          'dataSetName' => dataset_name,
-          'url' => url,
-          'columns' => column_json
-        }
-        response = self.class.post(endpoint_url, headers: @headers, body: body.to_json)
-        raise HttpException.new("There was a problem importing from url: #{response.code}.",
-                                "uploading dataset from #{url}",
-                                response) unless response.success?
-        NexosisApi::ImportsResponse.new(response.parsed_response)
-      end
-    end
-  end
-end
+require 'json'
+module NexosisApi
+  class Client
+    # Imports-based API operations
+    #
+    # @see http://docs.nexosis.com/
+    module Imports
+
+      # List all existing import requests
+      #
+      # @param dataset_name [String] optional name filter of dataset which was imported
+      # @param page [int] page number for items in list
+      # @param page_size [int] number of items in each page
+      # @return [NexosisApi::PagedArray of NexosisApi::ImportsResponse]
+      # @since 1.4 added paging parameters
+      def list_imports(dataset_name = '', page = 0, page_size = 50)
+        imports_url = '/imports'
+        query = {
+          dataSetName: dataset_name,
+          page: page,
+          pageSize: page_size
+        }
+        response = self.class.get(imports_url, headers: @headers, query: query)
+        if (response.success?)
+          NexosisApi::PagedArray.new(response.parsed_response,
+                                     response.parsed_response['items']
+                                     .map { |i| NexosisApi::ImportsResponse.new(i) })
+        else
+          raise HttpException.new("There was a problem getting the imports: #{response.code}.", "uploading dataset from s3 #{dataset_name}", response)
+        end
+      end
+
+      # Import a file from AWS s3 as your dataset
+      #
+      # @param dataset_name [String] the name to give to the new dataset or existing dataset to which this data will be upserted
+      # @param bucket_name [String] the AWS S3 bucket name in which the path will be found
+      # @param path [String] the path within the bucket (usually file name)
+      # @param region [String] the region in which your bucket exists. Defaults to us-east-1
+      # @param credentials [Hash] :access_key_id and :secret_access_key for user with rights to read the target file.
+      # @param column_metadata [Array of NexosisApi::Column] description of each column in target dataset. Optional.
+      # @return [NexosisApi::ImportsResponse]
+      # @see http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region for information on region names
+      # @note If credentials are provided they will be encrypted at the server, used once, and then removed from storage.
+      def import_from_s3(dataset_name, bucket_name, path, region = 'us-east-1', credentials = {}, column_metadata = [])
+        raise ArgumentError, 'dataset_name was not provided and is not optional ' unless dataset_name.to_s.empty? == false
+        raise ArgumentError, 'bucket_name was not provided and is not optional ' unless bucket_name.to_s.empty? == false
+        raise ArgumentError, 'path was not provided and is not optional ' unless path.to_s.empty? == false
+        s3_import_url = '/imports/s3'
+        column_json = Column.to_json(column_metadata)
+        body = {
+          'dataSetName' => dataset_name,
+          'bucket' => bucket_name,
+          'path' => path,
+          'region' => region,
+          'columns' => column_json
+        }
+        body['accessKeyId'] = credentials[:access_key_id] unless credentials.nil? || credentials[:access_key_id].nil?
+        body['secretAccessKey'] = credentials[:secret_access_key] unless credentials.nil? || credentials[:secret_access_key].nil?
+        response = self.class.post(s3_import_url, headers: @headers, body: body.to_json)
+        raise HttpException.new("There was a problem importing from s3: #{response.code}.",
+                                "uploading dataset from s3 #{dataset_name}",
+                                response) unless response.success?
+        NexosisApi::ImportsResponse.new(response.parsed_response)
+      end
+
+      # Get response back from import created previously. Presumably to check status.
+      #
+      # @param import_id [String] The id returned from a previous request to import
+      # @return [NexosisApi::ImportsResponse]
+      # @example get import
+      #    NexosisApi.client.retrieve_import('740dca2a-b488-4322-887e-fa473b1caa54')
+      def retrieve_import(import_id)
+        raise ArgumentError, 'import_id was not provided and is not optional ' unless import_id.to_s.empty? == false
+        imports_url = "/imports/#{import_id}"
+        response = self.class.get(imports_url, headers: @headers)
+        raise HttpException.new("There was a problem getting the import #{response.code}.",
+                                "requesting an import #{import_id}", response) unless response.success?
+        NexosisApi::ImportsResponse.new(response.parsed_response)
+      end
+
+      # Import a csv, json file (gzip'd or raw) from a Microsoft Azure storage blob
+      #
+      # @param dataset_name [String] the name to give to the new dataset or existing dataset to which this data will be upserted
+      # @param connection_string [String] the azure blob storage connection string providing access to the file resource
+      # @param container [String] the container in which the object is located.
+      # @param blob_name [String] the name of the object to import, usually a file. Always csv or json content.
+      # If folders have been used this will contain the full path within the container.
+      # @param column_metadata [Array of NexosisApi::Column] description of each column in target dataset. Optional.
+      # @return [NexosisApi::ImportsResponse]
+      # @since 2.0.0
+      # @note the connection string provided will be encrypted at the server, used once, and then removed from storage.
+      def import_from_azure(dataset_name, connection_string, container, blob_name, column_metadata = [])
+        raise ArgumentError, 'dataset_name was not provided and is not optional ' unless dataset_name.empty? == false
+        raise ArgumentError, 'connection_string was not provided and is not optional ' unless connection_string.empty? == false
+        raise ArgumentError, 'container was not provided and is not optional ' unless container.empty? == false
+        raise ArgumentError, 'blob_name was not provided and is not optional ' unless blob_name.empty? == false
+        azure_url = '/imports/azure'
+        column_json = Column.to_json(column_metadata)
+        body = {
+          'dataSetName' => dataset_name,
+          'connectionString' => connection_string,
+          'container' => container,
+          'blob' => blob_name,
+          'columns' => column_json
+        }
+        response = self.class.post(azure_url, headers: @headers, body: body.to_json)
+        raise HttpException.new("There was a problem importing from azure: #{response.code}.",
+                                "uploading dataset from azure #{dataset_name}",
+                                response) unless response.success?
+        NexosisApi::ImportsResponse.new(response.parsed_response)
+      end
+
+      # Import a csv or json file directly from any avaiable and reachable public endpoint.
+      #
+      # @param dataset_name [String] the name to give to the new dataset or existing dataset to which this data will be upserted
+      # @param url [String] the url indicating where to find the file resource to import
+      # @param column_metadata [Array of NexosisApi::Column] description of each column in target dataset. Optional.
+      # @param options [Hash] may provide basic auth credentials or a 'content-type' value to identify csv or json content.
+      # @return [NexosisApi::ImportsResponse]
+      # @note imports depend on file extensions, so use a content type indicator if json or csv cannot be inferred.
+      # @note Urls protected by basic auth can be accessed if given a userid and password in options
+      # @since 2.0.0
+      def import_from_url(dataset_name, url, column_metadata = [], options = {})
+        raise ArgumentError, 'dataset_name was not provided and is not optional ' unless dataset_name.empty? == false
+        raise ArgumentError, 'url was not provided and is not optional ' unless url.empty? == false
+        endpoint_url = '/imports/url'
+        column_json = Column.to_json(column_metadata)
+        body = {
+          'dataSetName' => dataset_name,
+          'url' => url,
+          'columns' => column_json
+        }
+        response = self.class.post(endpoint_url, headers: @headers, body: body.to_json)
+        raise HttpException.new("There was a problem importing from url: #{response.code}.",
+                                "uploading dataset from #{url}",
+                                response) unless response.success?
+        NexosisApi::ImportsResponse.new(response.parsed_response)
+      end
+    end
+  end
+end