bio-basespace-sdk 0.1.2

data/lib/basespace/api/base_api.rb

@@ -0,0 +1,242 @@
+# Copyright 2013 Toshiaki Katayama, Joachim Baran
+#
+#     Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+#     Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'basespace/api/api_client'
+require 'basespace/api/basespace_error'
+
+require 'net/https'
+require 'uri'
+
+Net::HTTP.version_1_2
+
+module Bio
+module BaseSpace
+
+# Parent class for BaseSpaceAPI and BillingAPI objects. It provides rudimentary
+# API access functionality.
+class BaseAPI
+
+  # Create a new BaseAPI instance using a given access token.
+  #
+  # +access_token+:: Access token provided by App triggering.
+  def initialize(access_token = nil)
+    if  $DEBUG
+      $stderr.puts "    # ----- BaseAPI#initialize ----- "
+      $stderr.puts "    # caller: #{caller}"
+      $stderr.puts "    # access_token: #{access_token}"
+      $stderr.puts "    # "
+    end
+    @api_client = nil
+    set_timeout(10)
+    set_access_token(access_token)        # logic for setting the access-token 
+  end
+
+  # Set a new access token. The value of a previously supplied access token
+  # is simply overwritten here.
+  #
+  # +access_token+:: Access token provided by App triggering.
+  def update_access_token(access_token)
+    @api_client.api_key = access_token
+  end
+
+  # Make a single request to the BaseSpace REST API.
+  #
+  # +my_model+:: Class or classname of the model that is applied in deserialization.
+  # +resource_path+:: URI that should be used for the API call.
+  # +method+:: HTTP method for the rest call (GET, POST, DELETE, etc.)
+  # +query_params+:: query parameters that should be sent along to the API.
+  # +header_params+:: Additional settings that should be transferred in the HTTP header.
+  # +post_data+:: Hash that contains data to be transferred.
+  # +verbose+:: Truth value indicating whether verbose output should be provided.
+  # +force_post+:: Truth value that indicates whether a POST should be forced.
+  # +no_api+:: (unclear; TODO)
+  def single_request(my_model, resource_path, method, query_params, header_params, post_data = nil, verbose = false, force_post = false, no_api = true)
+    # test if access-token has been set
+    if not @api_client and no_api
+      raise 'Access-token not set, use the "set_access_token"-method to supply a token value'
+    end
+    # Make the API Call
+    if verbose or $DEBUG
+      $stderr.puts "    # ----- BaseAPI#single_request ----- "
+      $stderr.puts "    # caller: #{caller}"
+      $stderr.puts "    # resource_path: #{resource_path}"
+      $stderr.puts "    # method: #{method}"
+      $stderr.puts "    # query_params: #{query_params}"
+      $stderr.puts "    # post_data: #{post_data}"
+      $stderr.puts "    # header_params: #{header_params}"
+      $stderr.puts "    # force_post: #{force_post}"
+      $stderr.puts "    # "
+    end
+    response = @api_client.call_api(resource_path, method, query_params, post_data, header_params, force_post)
+    if verbose or $DEBUG
+      $stderr.puts "    # ----- BaseAPI#single_request ----- "
+      $stderr.puts "    # response: #{response.inspect}"
+      $stderr.puts "    # "
+    end
+    unless response
+      raise 'BaseSpace error: None response returned'
+    end
+
+    # throw exception here for various error messages
+    if response['ResponseStatus'].has_key?('ErrorCode')
+      raise "BaseSpace error: #{response['ResponseStatus']['ErrorCode']}: #{response['ResponseStatus']['Message']}"
+    end
+     
+    # Create output objects if the response has more than one object
+    response_object = @api_client.deserialize(response, my_model)
+    return response_object.response
+  end
+
+  # Send a list request to the BaseSpace REST API.
+  #
+  # +my_model+:: Class or classname of the model that is applied in deserialization.
+  # +resource_path+:: URI that should be used for the API call.
+  # +method+:: HTTP method for the rest call (GET, POST, DELETE, etc.)
+  # +query_params+:: query parameters that should be sent along to the API.
+  # +header_params+:: Additional settings that should be transferred in the HTTP header.
+  # +verbose+:: Truth value indicating whether verbose output should be provided.
+  # +no_api+:: (unclear; TODO)
+  def list_request(my_model, resource_path, method, query_params, header_params, verbose = false, no_api = true)
+    # test if access-token has been set
+    if not @api_client and no_api
+      raise 'Access-token not set, use the "set_access_token"-method to supply a token value'
+    end
+    
+    # Make the API Call
+    if verbose or $DEBUG
+      $stderr.puts "    # ----- BaseAPI#list_request ----- "
+      $stderr.puts "    # caller: #{caller}"
+      $stderr.puts "    # Path: #{resource_path}"
+      $stderr.puts "    # Pars: #{query_params}"
+      $stderr.puts "    # "
+    end
+    response = @api_client.call_api(resource_path, method, query_params, nil, header_params)  # post_data = nil
+    if verbose or $DEBUG
+      $stderr.puts "    # ----- BaseAPI#list_request ----- "
+      $stderr.puts "    # response: #{response.inspect}"
+      $stderr.puts "    # "
+    end
+    unless response
+      raise "BaseSpace Exception: No data returned"
+    end
+    unless response.kind_of?(Array)  # list
+      response = [response]
+    end
+    response_objects = []
+    response.each do |response_object|
+      response_objects << @api_client.deserialize(response_object, 'ListResponse')
+    end
+    
+    # convert list response dict to object type
+    # TODO check that Response is present -- errors sometime don't include
+    # [TODO] check why the Python SDK only uses the first element in the response_objects
+    convertet = []
+    if response_object = response_objects.first
+      response_object.convert_to_object_list.each do |c|
+        convertet << @api_client.deserialize(c, my_model)
+      end
+    end
+    return convertet
+  end
+
+  # URL encode a Hash of data values.
+  #
+  # +hash+:: data encoded in a Hash.
+  def hash2urlencode(hash)
+    # URI.escape (alias URI.encode) is obsolete since Ruby 1.9.2.
+    #return hash.map{|k,v| URI.encode(k.to_s) + "=" + URI.encode(v.to_s)}.join("&")
+    return hash.map{|k,v| URI.encode_www_form_component(k.to_s) + "=" + URI.encode_www_form_component(v.to_s)}.join("&")
+  end
+
+  # Post data to the given BaseSpace API URL. Method name is a bit of a 
+  # misnomer, because 'curl' is not used by this method -- instead only
+  # Ruby core classes are used.
+  #
+  # +data+:: Data that should be transferred to the API.
+  # +url+:: URL of the BaseSpace API.
+  def make_curl_request(data, url)
+    if $DEBUG
+      $stderr.puts "    # ----- BaseAPI#make_curl_request ----- "
+      $stderr.puts "    # caller: #{caller}"
+      $stderr.puts "    # data: #{data}"
+      $stderr.puts "    # url: #{url}"
+      $stderr.puts "    # "
+    end
+    post = hash2urlencode(data)
+    uri = URI.parse(url)
+    #res = Net::HTTP.post_form(uri, post).body
+    http_opts = {}
+    if uri.scheme == "https"
+      http_opts[:use_ssl] = true
+    end
+    res = Net::HTTP.start(uri.host, uri.port, http_opts) { |http|
+      http.post(uri.path, post)
+    }
+    obj = JSON.parse(res.body)
+    if $DEBUG
+      $stderr.puts "    # res: #{res}"
+      $stderr.puts "    # obj: #{obj}"
+      $stderr.puts "    # "
+    end
+    if obj.has_key?('error')
+      raise "BaseSpace exception: " + obj['error'] + " - " + obj['error_description']
+    end
+    return obj
+  end
+    
+  # Return a string representation of this object.
+  def to_s
+    return "BaseSpaceAPI instance - using token=#{get_access_token}"
+  end
+
+  # Return a string representation of this object.
+  def to_str
+    return self.to_s
+  end
+
+  # Specify the timeout in seconds for each request.
+  #
+  # +param time+:: Timeout in second.
+  def set_timeout(time)
+    @timeout = time
+    if @api_client
+      @api_client.timeout = @timeout
+    end
+  end
+  
+  # Sets a new API token.
+  #
+  # +token+:: New API token.
+  def set_access_token(token)
+    @api_client = nil
+    if token
+      @api_client = APIClient.new(token, @api_server, @timeout)
+    end
+  end
+
+  # Returns the access-token that was used to initialize the BaseSpaceAPI object.
+  def get_access_token
+    if @api_client
+      return @api_client.api_key
+    end
+    return ""  # [TODO] Should return nil in Ruby?
+  end
+  
+  # Returns the server URI used by this instance.
+  def get_server_uri
+    return @api_client.api_server
+  end
+end
+
+end # module BaseSpace
+end # module Bio

data/lib/basespace/api/basespace_api.rb

@@ -0,0 +1,789 @@
+# Copyright 2013 Toshiaki Katayama, Joachim Baran
+#
+#     Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+#     Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'basespace/api/api_client'
+require 'basespace/api/base_api'
+require 'basespace/api/basespace_error'
+require 'basespace/model/query_parameters'
+
+require 'net/https'
+require 'uri'
+require 'json'
+
+Net::HTTP.version_1_2
+
+module Bio
+module BaseSpace
+
+# The main API class used for all communication with the BaseSpace REST server.
+class BaseSpaceAPI < BaseAPI
+
+  # URIs for obtaining a access token, user verification code, and app trigger information.
+  TOKEN_URL      = '/oauthv2/token'
+  DEVICE_URL     = "/oauthv2/deviceauthorization"
+  WEB_AUTHORIZE  = '/oauth/authorize'
+
+  attr_reader :app_session_id
+
+  # Load credentials and start a new BaseSpace session.
+  def self.start
+    if opts = Bio::BaseSpace.load_credentials
+      self.new(opts['client_id'], opts['client_secret'], opts['basespace_url'], opts['api_version'], opts['app_session_id'], opts['access_token'])
+    else
+      raise "Please specify your BaseSpace credentials in the credentials.json file or use Bio::BaseSpace::BaseSpaceAPI.new with arguments"
+    end
+  end
+
+  # Create a new object for communicating with the BaseSpace REST server; preferred method of calling
+  # is through the 'start' class method.
+  #
+  # +client_key+:: Client key to use for authentication (provided when registering an App).
+  # +client_secret+:: Client secret key to use for authentication (provided when registering an App).
+  # +api_server+:: URI of the BaseSpace API server.
+  # +version+:: API version to use.
+  # +app_session_id+:: App session ID that was generated by application triggering.
+  # +access_token+:: Access token provided by App triggering.
+  def initialize(client_key, client_secret, api_server, version, app_session_id = nil, access_token = nil)
+    end_with_slash = %r(/$)
+    unless api_server[end_with_slash]
+      api_server += '/'
+    end
+    
+    @app_session_id  = app_session_id
+    @key             = client_key
+    @secret          = client_secret
+    @api_server      = api_server + version
+    @version         = version
+    @weburl          = api_server.sub('api.', '')
+    @timeout         = nil
+
+    super(access_token)
+  end
+
+  # This method is not for general use and should only be called from 'get_app_session'.
+  #
+  # +obj+:: Application trigger JSON.
+  def get_trigger_object(obj)
+    if obj['ResponseStatus'].has_key?('ErrorCode')
+      raise 'BaseSpace error: ' + obj['ResponseStatus']['ErrorCode'].to_s + ": " + obj['ResponseStatus']['Message']
+    end
+    #access_token = nil  # '' is false in Python but APIClient.new only raises when the value is None (not '')
+    access_token = ''
+    temp_api = APIClient.new(access_token, @api_server)
+    response = temp_api.deserialize(obj, 'AppSessionResponse')
+    # AppSessionResponse object has a response method which returns a AppSession object
+    app_sess = response.get_attr('Response')
+    # AppSession object has a serialize_references method which converts an array of
+    # AppSessionLaunchObject objects by calling serialize_object method in each object.
+    # The method in turn calls the serialize_object method of the given BaseSpaceAPI object
+    # with @content ('dict') and @type ('str') arguments. Returns an array of serialized objects.
+    res = app_sess.serialize_references(self)
+    return res
+  end
+  
+  def serialize_object(d, type)
+    # [TODO] None (nil) or '' ?
+    #access_token = nil
+    access_token = ''
+    temp_api = APIClient.new(access_token, @api_server)
+    if type.downcase == 'project'
+      return temp_api.deserialize(d, 'Project')
+    end
+    if type.downcase == 'sample'
+      return temp_api.deserialize(d, 'Sample')
+    end
+    if type.downcase == 'appresult'
+      return temp_api.deserialize(d, 'AppResult')
+    end
+    return d
+  end
+
+
+  # Returns the AppSession instance identified by the given ID.
+  #
+  # +id+:: The ID of the AppSession.
+  def get_app_session_by_id(id)
+    # TO_DO make special case for access-token only retrieval
+    return get_app_session(id)
+  end
+
+  # Returns an AppSession instance containing user and data-type the app was triggered by/on.
+  #
+  # +id+:: The AppSessionId, ID not supplied the AppSessionId used for instantiating the BaseSpaceAPI instance.
+  def get_app_session(id = nil)
+    if (not @app_session_id) and (not id)
+      raise "This BaseSpaceAPI instance has no app_session_id set and no alternative id was supplied for method get_app_session"
+    end
+
+    # if (not id) and (not @key)
+    #   raise "This BaseSpaceAPI instance has no client_secret (key) set and no alternative id was supplied for method get_app_session"
+    # end
+    
+    resource_path = @api_server + '/appsessions/{AppSessionId}'
+    if id
+      resource_path = resource_path.sub('{AppSessionId}', id)
+    else
+      resource_path = resource_path.sub('{AppSessionId}', @app_session_id)
+    end
+    if $DEBUG
+      $stderr.puts "    # ----- BaseSpaceAPI#get_app_session ----- "
+      $stderr.puts "    # resource_path: #{resource_path}"
+      $stderr.puts "    # "
+    end
+    uri = URI.parse(resource_path)
+    uri.user = @key
+    uri.password = @secret
+    #response = Net::HTTP.get(uri)
+    http_opts = {}
+    if uri.scheme == "https"
+      http_opts[:use_ssl] = true
+    end
+    response = Net::HTTP.start(uri.host, uri.port, http_opts) { |http|
+      request = Net::HTTP::Get.new(uri.path)
+      request.basic_auth uri.user, uri.password
+      http.request(request)
+    }
+    obj = JSON.parse(response.body)
+    # TODO add exception if response isn't OK, e.g. incorrect server gives path not recognized
+    return get_trigger_object(obj)
+  end
+
+  # Request access to a data object.
+  #
+  # +obj+:: The data object we wish to get access to.
+  # +access_type+:: The type of access (read|write), default is write.
+  # +web+:: True if the App is web-based, default is false meaning a device based App.
+  # +redirect_url+:: For the web-based case, a redirection URL.
+  # +state+:: (unclear from Python port)
+  def get_access(obj, access_type = 'write', web = nil, redirect_url = nil, state = nil)
+    scope_str = obj.get_access_str(access_type)
+    if web
+      return get_web_verification_code(scope_str, redirect_url, state)
+    else
+      return get_verification_code(scope_str)
+    end
+  end
+      
+  # Returns the BaseSpace dictionary containing the verification code and verification URL for the user to approve
+  # access to a specific data scope.  
+  # 
+  # Corresponding curl call:
+  # curlCall = 'curl -d "response_type=device_code" -d "client_id=' + client_key + '" -d "scope=' + scope + '" ' + DEVICE_URL
+  # 
+  # For details see:
+  # https://developer.basespace.illumina.com/docs/content/documentation/authentication/obtaining-access-tokens
+  # 
+  # +scope+:: The scope that access is requested for.
+  def get_verification_code(scope)
+    #curlCall = 'curl -d "response_type=device_code" -d "client_id=' + @key + '" -d "scope=' + scope + '" ' + @api_server + DEVICE_URL
+    #puts curlCall
+    unless @key
+      raise "This BaseSpaceAPI instance has no client_secret (key) set and no alternative id was supplied for method get_verification_code"
+    end
+    data = {'client_id' => @key, 'scope' => scope, 'response_type' => 'device_code'}
+    return make_curl_request(data, @api_server + DEVICE_URL)
+  end
+
+  # Generates the URL the user should be redirected to for web-based authentication.
+  #  
+  # +scope+: The scope that access is requested for.
+  # +redirect_url+:: The redirect URL.
+  # +state+:: An optional state parameter that will passed through to the redirect response.
+  def get_web_verification_code(scope, redirect_url, state = nil)
+    if (not @key)
+      raise "This BaseSpaceAPI instance has no client_id (key) set and no alternative id was supplied for method get_verification_code"
+    end
+    data = {'client_id' => @key, 'redirect_uri' => redirect_url, 'scope' => scope, 'response_type' => 'code', "state" => state}
+    return @weburl + WEB_AUTHORIZE + '?' + hash2urlencode(data)
+  end
+
+  # Returns a user specific access token.    
+  #
+  # +device_code+:: The device code returned by the verification code method.
+  def obtain_access_token(device_code)
+    if (not @key) or (not @secret)
+      raise "This BaseSpaceAPI instance has either no client_secret or no client_id set and no alternative id was supplied for method get_verification_code"
+    end
+    data = {'client_id' => @key, 'client_secret' => @secret, 'code' => device_code, 'grant_type' => 'device', 'redirect_uri' => 'google.com'}
+    dict = make_curl_request(data, @api_server + TOKEN_URL)
+    return dict['access_token']
+  end
+
+  def update_privileges(code)
+    token = obtain_access_token(code)
+    set_access_token(token)
+  end
+
+  # Creates a project with the specified name and returns a project object. 
+  # If a project with this name already exists, the existing project is returned.
+  #
+  # +name+:: Name of the project.
+  def create_project(name)
+    #: v1pre3/projects, it requires 1 input parameter which is Name
+    my_model       = 'ProjectResponse'
+    resource_path  = '/projects/'
+    resource_path  = resource_path.sub('{format}', 'json')
+    method         = 'POST'
+    query_params   = {}
+    header_params  = {}
+    post_data      = {}
+    post_data['Name']  = name
+    verbose        = false
+    return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose)
+  end
+          
+  # Returns the User object corresponding to ID.
+  #
+  # +id+:: The ID of the user.
+  def get_user_by_id(id)
+    my_model       = 'UserResponse'
+    resource_path  = '/users/{Id}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+    return single_request(my_model, resource_path, method, query_params, header_params)
+  end
+         
+  # Returns an AppResult object corresponding to ID.
+  #
+  # +param id+:: The ID of the AppResult.
+  def get_app_result_by_id(id)
+    my_model       = 'AppResultResponse'
+    resource_path  = '/appresults/{Id}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+    return single_request(my_model, resource_path, method, query_params, header_params)
+  end
+
+  # Returns a list of File objects for the AppResult with the given ID.
+  # 
+  # +id+:: The ID of the AppResult.
+  # +qp: An object of type QueryParameters for custom sorting and filtering.
+  def get_app_result_files(id, qp = {})
+    query_pars     = qp.kind_of?(Hash) ? QueryParameters.new(qp) : qp
+    query_pars.validate
+    my_model       = 'File'
+    resource_path  = '/appresults/{Id}/files'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = query_pars.get_parameter_dict
+    header_params  = {}
+    verbose        = false
+    return list_request(my_model, resource_path, method, query_params, header_params, verbose)
+  end
+
+  # Request a project object by ID.
+  # 
+  # +id+:: The ID of the project.
+  def get_project_by_id(id)
+    my_model       = 'ProjectResponse'
+    resource_path  = '/projects/{Id}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+    return single_request(my_model, resource_path, method, query_params, header_params)
+  end
+         
+  # Returns a list available projects for a User with the specified ID.
+  # 
+  # +id+:: The ID of the user.
+  # +qp+:: An object of type QueryParameters for custom sorting and filtering.
+  def get_project_by_user(id, qp = {})
+    query_pars     = qp.kind_of?(Hash) ? QueryParameters.new(qp) : qp
+    query_pars.validate
+    my_model       = 'Project'
+    resource_path  = '/users/{Id}/projects'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id) if id != nil
+    method         = 'GET'
+    query_params   = query_pars.get_parameter_dict
+    header_params  = {}
+    return list_request(my_model, resource_path, method, query_params, header_params)
+  end
+     
+  # Returns a list of accessible runs for the User with the given ID.
+  # 
+  # +id+:: User id.
+  # +qp+:: An object of type QueryParameters for custom sorting and filtering.
+  def get_accessible_runs_by_user(id, qp = {})
+    query_pars     = qp.kind_of?(Hash) ? QueryParameters.new(qp) : qp
+    query_pars.validate
+    my_model       = 'RunCompact'
+    resource_path  = '/users/{Id}/runs'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = query_pars.get_parameter_dict
+    header_params  = {}
+    return list_request(my_model, resource_path, method, query_params, header_params)
+  end
+  
+  # Returns a list of AppResult object associated with the project with ID.
+  # 
+  # +id+:: The project ID.
+  # +qp+:: An object of type QueryParameters for custom sorting and filtering.
+  # +statuses+:: A list of AppResult statuses to filter by.
+  def get_app_results_by_project(id, qp = {}, statuses = [])
+    query_pars     = qp.kind_of?(Hash) ? QueryParameters.new(qp) : qp
+    query_pars.validate
+    my_model       = 'AppResult'
+    resource_path  = '/projects/{Id}/appresults'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = query_pars.get_parameter_dict
+    unless statuses.empty?
+      query_params['Statuses'] = statuses.join(",")
+    end
+    header_params  = {}
+    verbose        = false
+    return list_request(my_model, resource_path, method, query_params, header_params, verbose)
+  end
+
+  # Returns a list of samples associated with a project with ID.
+  # 
+  # +id+:: The ID of the project.
+  # +qp+:: An object of type QueryParameters for custom sorting and filtering.
+  def get_samples_by_project(id, qp = {})
+    query_pars     = qp.kind_of?(Hash) ? QueryParameters.new(qp) : qp
+    query_pars.validate
+    my_model       = 'Sample'
+    resource_path  = '/projects/{Id}/samples'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = query_pars.get_parameter_dict
+    header_params  = {}
+    verbose        = false
+    return list_request(my_model, resource_path, method, query_params, header_params, verbose)
+  end
+
+  # Returns a Sample object.
+  # 
+  # +id+:: The ID of the sample.
+  def get_sample_by_id(id)
+    my_model       = 'SampleResponse'
+    resource_path  = '/samples/{Id}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+    post_data      = nil
+    verbose        = false
+    return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose)
+  end
+
+  # Returns a list of File objects associated with sample with ID.
+  # 
+  # +id+:: Sample ID.
+  # +qp+:: An object of type QueryParameters for custom sorting and filtering.
+  def get_files_by_sample(id, qp = {})
+    query_pars     = qp.kind_of?(Hash) ? QueryParameters.new(qp) : qp
+    query_pars.validate
+    my_model       = 'File'
+    resource_path  = '/samples/{Id}/files'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = query_pars.get_parameter_dict
+    header_params  = {}
+    verbose        = false
+    return list_request(my_model, resource_path, method, query_params, header_params, verbose)
+  end
+  
+  # Returns a file object by ID.
+  # 
+  # +id+:: The ID of the file.
+  def get_file_by_id(id)
+    my_model       = 'FileResponse'
+    resource_path  = '/files/{Id}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+    post_data      = nil
+    verbose        = false
+    return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose)
+  end
+
+  # Returns an instance of Genome with the specified ID.
+  # 
+  # +id+:: The genome ID.
+  def get_genome_by_id(id)
+    my_model       = 'GenomeResponse'
+    resource_path  = '/genomes/{Id}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+    return single_request(my_model, resource_path, method, query_params, header_params)
+  end
+
+  # Returns a list of all available genomes.
+  # 
+  # +qp+:: An object of type QueryParameters for custom sorting and filtering.
+  def get_available_genomes(qp = {})
+    query_pars     = qp.kind_of?(Hash) ? QueryParameters.new(qp) : qp
+    query_pars.validate
+    my_model       = 'GenomeV1'
+    resource_path  = '/genomes'
+    resource_path  = resource_path.sub('{format}', 'json')
+    method         = 'GET'
+    query_params   = query_pars.get_parameter_dict
+    header_params  = {}
+    verbose        = false
+    return list_request(my_model, resource_path, method, query_params, header_params, verbose)
+  end
+  
+  # TODO, needs more work in parsing meta data, currently only map keys are returned.
+  
+  # Returns a VariantMetadata object for a variant file.
+  # 
+  # +id+:: ID of the VCF file.
+  # +format+:: Set to 'vcf' to get the results as lines in VCF format.
+  def get_variant_metadata(id, format)
+    my_model       = 'VariantsHeaderResponse'
+    resource_path  = '/variantset/{Id}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    query_params['Format'] = @api_client.to_path_value(format)
+    header_params  = {}
+    verbose        = false
+    return single_request(my_model, resource_path, method, query_params, header_params, verbose)
+  end
+  
+  # List the variants in a set of variants. Maximum returned records is 1000.
+  # 
+  # +id+:: ID of the variant file.
+  # +chrom+:: The chromosome of interest.
+  # +start_pos+:: The start position of the sequence of interest.
+  # +end_pos+:: The start position of the sequence of interest.
+  # +format+:: Set to 'vcf' to get the results as lines in VCF format.
+  # +qp+:: An (optional) object of type QueryParameters for custom sorting and filtering.
+  def filter_variant_set(id, chrom, start_pos, end_pos, format, qp = {'SortBy' => 'Position'})
+    query_pars     = qp.kind_of?(Hash) ? QueryParameters.new(qp) : qp
+    query_pars.validate
+    my_model       = 'Variant'
+    resource_path  = '/variantset/{Id}/variants/chr{Chrom}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Chrom}', chrom)
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = query_pars.get_parameter_dict
+    header_params  = {}
+    query_params['StartPos']  = start_pos
+    query_params['EndPos']    = end_pos
+    query_params['Format']    = format
+    verbose        = false
+    return list_request(my_model, resource_path, method, query_params, header_params, verbose)
+  end
+  
+  # Mean coverage levels over a sequence interval. Returns an instance of CoverageResponse.
+  # 
+  # +id+:: Chromosome to query.
+  # +chrom+:: The ID of the resource.
+  # +start_pos+:: Get coverage starting at this position. Default is 1.
+  # +end_pos+:: Get coverage up to and including this position. Default is start_pos + 1280.
+  def get_interval_coverage(id, chrom, start_pos = nil, end_pos = nil)
+    my_model       = 'CoverageResponse'
+    resource_path  = '/coverage/{Id}/{Chrom}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Chrom}', chrom)
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+    query_params['StartPos']  = @api_client.to_path_value(start_pos)
+    query_params['EndPos']    = @api_client.to_path_value(end_pos)
+    post_data      = nil
+    verbose        = false
+    return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose)
+  end
+
+  # Returns Metadata about coverage as a CoverageMetadata instance.
+  # 
+  # +id+:: ID of a BAM file.
+  # +chrom+:: Chromosome to query.
+  def get_coverage_meta_info(id, chrom)
+    my_model       = 'CoverageMetaResponse'
+    resource_path  = '/coverage/{Id}/{Chrom}/meta'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Chrom}', chrom)
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+    post_data      = nil
+    verbose        = false
+    return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose)
+  end
+   
+  # Create an AppResult object.
+  # 
+  # +id+:: ID of the project in which the AppResult is to be added.
+  # +name+:: The name of the AppResult.
+  # +desc+:: A describtion of the AppResult.
+  # +samples+:: List of samples (if any).
+  # +app_session_id+:: If no app_session_id is given, the id used to initialize the BaseSpaceAPI instance will be used. If app_session_id is set equal to an empty string, a new appsession will be created.
+  def create_app_result(id, name, desc, samples = [], app_session_id = nil)
+    if (not @app_session_id) and (not app_session_id)
+      raise "This BaseSpaceAPI instance has no app_session_id set and no alternative id was supplied for method create_app_result"
+    end
+    
+    my_model       = 'AppResultResponse'
+    resource_path  = '/projects/{ProjectId}/appresults'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{ProjectId}', id)
+    method         = 'POST'
+    query_params   = {}
+    header_params  = {}
+    post_data      = {}
+    verbose        = false
+    
+    if app_session_id
+      query_params['appsessionid']  = app_session_id
+    else
+      query_params['appsessionid']  = @app_session_id      # default case, we use the current appsession
+    end
+    
+    # add the sample references
+    if samples.length > 0
+      ref = []
+      samples.each do |s|
+        d = { "Rel" => "using", "Type" => "Sample", "HrefContent" => @version + '/samples/' + s.id }
+        ref << d
+      end
+      post_data['References']  = ref
+    end
+
+    # case, an appSession is provided, we need to check if the a
+    if query_params.has_key?('appsessionid')
+      sid = query_params['appsessionid']
+      session = get_app_session(sid)
+      unless session.can_work_on
+        raise 'AppSession status must be "running," to create and AppResults. Current status is ' + session.status
+      end
+    end
+        
+    post_data['Name']         = name
+    post_data['Description']  = desc
+    return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose)
+  end
+          
+  # Uploads a file associated with an AppResult to BaseSpace and returns the corresponding file object.
+  # 
+  # +id+:: AppResult ID.
+  # +local_path+:: The local path to the file to be uploaded.
+  # +file_name+:: The desired filename in the AppResult folder on the BaseSpace server.
+  # +directory+:: The directory the file should be placed in.
+  # +content_type+:: The content-type of the file.
+  def app_result_file_upload(id, local_path, file_name, directory, content_type, multipart = 0)
+    my_model       = 'FileResponse'
+    resource_path  = '/appresults/{Id}/files'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'POST'
+    query_params   = {}
+    header_params  = {}
+    verbose        = false
+
+    query_params['name']           = file_name
+    query_params['directory']      = directory 
+    header_params['Content-Type']  = content_type
+
+    # three cases, two for multipart, starting 
+    if multipart == 1
+      query_params['multipart']  = 'true'
+      post_data    = nil
+      force_post   = true
+      # Set force post as this need to use POST though no data is being streamed
+      return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose, force_post)
+    elsif multipart == 2
+      query_params = {'uploadstatus' => 'complete'}
+      post_data    = nil
+      force_post   = true
+      # Set force post as this need to use POST though no data is being streamed
+      return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose, force_post)
+    else
+      post_data = File.open(local_path).read
+      return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose)
+    end
+  end
+
+  # Downloads a BaseSpace file to a local directory.
+  # 
+  # +id+:: File ID.
+  # +local_dir+:: The local directory to place the file in.
+  # +name+:: The name of the local file.
+  # +range+:: The byte range of the file to retrieve (not yet implemented).
+  def file_download(id, local_dir, name, range = [])  #@ReservedAssignment
+    resource_path  = '/files/{Id}/content'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+
+    query_params['redirect'] = 'meta' # we need to add this parameter to get the Amazon link directly 
+    
+    response = @api_client.call_api(resource_path, method, query_params, nil, header_params)
+    if response['ResponseStatus'].has_key?('ErrorCode')
+      raise 'BaseSpace error: ' + response['ResponseStatus']['ErrorCode'].to_s + ": " + response['ResponseStatus']['Message']
+    end
+    
+    # get the Amazon URL 
+    file_url = response['Response']['HrefContent']
+
+    header = nil
+    unless range.empty?
+      # puts "Case range request" 
+      header = { 'Range' => format('bytes=%s-%s', range[0], range[1]) }
+    end
+    
+    # Do the download
+    File.open(File.join(local_dir, name), "wb") do |fp|
+      http_opts = {}
+      if uri.scheme == "https"
+        http_opts[:use_ssl] = true
+      end
+      uri = URI.parse(file_url)
+      res = Net::HTTP.start(uri.host, uri.port, http_opts) { |http|
+        # [TODO] Do we need user and pass here also?
+        http.get(uri.path, header)
+      }
+      fp.print res.body
+    end
+
+    return 1
+  end
+
+  # Returns URL of a file on S3.
+  # 
+  # +id+:: File ID.
+  def file_url(id)  # @ReservedAssignment
+    resource_path  = '/files/{Id}/content'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'GET'
+    query_params   = {}
+    header_params  = {}
+
+    query_params['redirect'] = 'meta' # we need to add this parameter to get the Amazon link directly 
+    
+    response = @api_client.call_api(resource_path, method, query_params, nil, header_params)
+    if response['ResponseStatus'].has_key?('ErrorCode')
+      raise 'BaseSpace error: ' + response['ResponseStatus']['ErrorCode'].to_s + ": " + response['ResponseStatus']['Message']
+    end
+    
+    # return the Amazon URL 
+    return response['Response']['HrefContent']
+  end
+
+
+  # Helper method for uploading multipart files, do not call directly.
+  # 
+  # +id+:: File ID.
+  # +part_number+:: File part to be uploaded.
+  # +md5+:: MD5 sum of datastream.
+  # +data+:: The data-stream to be uploaded.
+  def upload_multipart_unit(id, part_number, md5, data)
+    resource_path  = '/files/{Id}/parts/{partNumber}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    resource_path  = resource_path.sub('{partNumber}', part_number.to_s)
+    method         = 'PUT'
+    query_params   = {}
+    header_params  = {'Content-MD5' => md5.strip()}
+    force_post     = false
+    out = @api_client.call_api(resource_path, method, query_params, data, header_params, force_post)
+    return out
+    # curl -v -H "x-access-token: {access token}" \
+    #   -H "Content-MD5: 9mvo6qaA+FL1sbsIn1tnTg==" \
+    #   -T reportarchive.zipaa \
+    #   -X PUT https://api.cloud-endor.illumina.com/v1pre2/files/7094087/parts/1
+  end
+
+  # Not yet implemented (by Illumina Python SDK)
+  #
+  # def large_file_download
+  #   raise 'Not yet implemented'
+  # end
+  
+  # Method for multi-threaded file-upload for parallel transfer of very large files (currently only runs on unix systems)
+  # 
+  # 
+  # :param id: The AppResult ID
+  # :param local_path: The local path of the file to be uploaded
+  # :param file_name: The desired filename on the server
+  # :param directory: The server directory to place the file in (empty string will place it in the root directory)
+  # :param content_type: The content type of the file
+  # :param tempdir: Temp directory to use, if blank the directory for 'local_path' will be used
+  # :param cpuCount: The number of CPUs to be used
+  # :param partSize: The size of individual upload parts (must be between 5 and 25mb)
+  # :param verbose: Write process output to stdout as upload progresses
+  #
+  # def multipart_file_upload(self, id, local_path, file_name, directory, content_type, tempdir = nil, cpuCount = 2, partSize = 25, verbose = false)
+  #   # Create file object on server
+  #   multipart = 1
+  #   my_file = app_result_file_upload(id, local_path, file_name, directory, content_type, multipart)
+  #
+  #   # prepare multi-par upload objects
+  #   my_mpu = mpu(self, id, local_path, my_file, cpu_count, part_size, tempdir, verbose)
+  #   return my_mpu
+  # end
+  #
+  # def mark_file_state(id)
+  # end
+
+  # Set the status of an AppResult object.
+  # 
+  # +id+:: The id of the AppResult.
+  # +status+:: Status assignment string.
+  # +summary+:: Summary string.
+  def set_app_session_state(id, status, summary)
+    my_model       = 'AppSessionResponse'
+    resource_path  = '/appsessions/{Id}'
+    resource_path  = resource_path.sub('{format}', 'json')
+    resource_path  = resource_path.sub('{Id}', id)
+    method         = 'POST'
+    query_params   = {}
+    header_params  = {}
+    post_data      = {}
+    verbose        = false
+
+    status_allowed = ['running', 'complete', 'needsattention', 'aborted', 'error']
+    unless status_allowed.include?(status.downcase)
+      raise "AppResult state must be in #{status_allowed.inspect}"
+    end
+    post_data['status']         = status.downcase
+    post_data['statussummary']  = summary
+    return single_request(my_model, resource_path, method, query_params, header_params, post_data, verbose)
+  end
+end
+
+end # module BaseSpace
+end # module Bio
+