occi 2.5.19 → 3.0.0.beta.0

data/lib/occi/api/client/client_http.rb

@@ -0,0 +1,922 @@
+require 'rubygems'
+require 'httparty'
+require 'occi/api/client/http/net_http_fix'
+require 'occi/api/client/http/httparty_fix'
+
+module Occi
+  module Api
+    module Client
+
+    class ClientHttp
+
+      # HTTParty for raw HTTP requests
+      include HTTParty
+
+      # TODO: uncomment the following line as JSON is properly implemented in OpenStack
+      # headers 'Accept' => 'application/occi+json,text/plain;q=0.8,text/occi;q=0.2'
+      headers 'Accept' => 'text/plain,text/occi;q=0.2'
+
+      # a few attributes which should be visible outside the client
+      attr_reader :endpoint
+      attr_reader :auth_options
+      attr_accessor :media_type
+      attr_reader :connected
+      attr_accessor :model
+      attr_reader :logger
+      attr_reader :last_response
+
+      # hash mapping HTTP response codes to human-readable messages
+      HTTP_CODES = {
+          "100" => "Continue",
+          "101" => "Switching Protocols",
+          "200" => "OK",
+          "201" => "Created",
+          "202" => "Accepted",
+          "203" => "Non-Authoritative Information",
+          "204" => "No Content",
+          "205" => "Reset Content",
+          "206" => "Partial Content",
+          "300" => "Multiple Choices",
+          "301" => "Moved Permanently",
+          "302" => "Found",
+          "303" => "See Other",
+          "304" => "Not Modified",
+          "305" => "Use Proxy",
+          "307" => "Temporary Redirect",
+          "400" => "Bad Request",
+          "401" => "Unauthorized",
+          "402" => "Payment Required",
+          "403" => "Forbidden",
+          "404" => "Not Found",
+          "405" => "Method Not Allowed",
+          "406" => "Not Acceptable",
+          "407" => "Proxy Authentication Required",
+          "408" => "Request Time-out",
+          "409" => "Conflict",
+          "410" => "Gone",
+          "411" => "Length Required",
+          "412" => "Precondition Failed",
+          "413" => "Request Entity Too Large",
+          "414" => "Request-URI Too Large",
+          "415" => "Unsupported Media Type",
+          "416" => "Requested range not satisfiable",
+          "417" => "Expectation Failed",
+          "500" => "Internal Server Error",
+          "501" => "Not Implemented",
+          "502" => "Bad Gateway",
+          "503" => "Service Unavailable",
+          "504" => "Gateway Time-out",
+          "505" => "HTTP Version not supported"
+      }
+
+      # Initializes client data structures and retrieves OCCI model
+      # from the server.
+      #
+      # @example
+      #    Occi::Api::Client::ClientHttp.new # => #<Occi::Api::Client::ClientHttp>
+      #
+      # @param [String] endpoint URI
+      # @param [Hash] auth options in a hash
+      # @param [Hash] logging options in a hash
+      # @param [Boolean] enable autoconnect
+      # @param [String] media type identifier
+      # @return [Occi::Api::Client::ClientHttp] client instance
+      def initialize(endpoint = "http://localhost:3000/", auth_options = { :type => "none" },
+                     log_options = { :out => STDERR, :level => Occi::Log::WARN, :logger => nil },
+                     auto_connect = true, media_type = nil)
+        # set Occi::Log
+        set_logger log_options
+
+        # pass auth options to HTTParty
+        change_auth auth_options
+
+        # check the validity and canonize the endpoint URI
+        prepare_endpoint endpoint
+
+        # get accepted media types from HTTParty
+        set_media_type
+
+        # force media_type if provided
+        if media_type
+          self.class.headers 'Accept' => media_type
+          @media_type = media_type
+        end
+
+        Occi::Log.debug("Media Type: #{@media_type}")
+        Occi::Log.debug("Headers: #{self.class.headers}")
+
+        # get model information from the endpoint
+        # and create Occi::Model instance
+        set_model
+
+        # auto-connect?
+        @connected = auto_connect
+      end
+
+      # Creates a new resource instance, resource should be specified
+      # by its name or identifier.
+      #
+      # @example
+      #   client.get_resource "compute" # => Occi::Core::Resource
+      #   client.get_resource "storage" # => Occi::Core::Resource
+      #   client.get_resource "http://schemas.ogf.org/occi/infrastructure#network"
+      #    # => Occi::Core::Resource
+      #
+      # @param [String] resource name or resource identifier
+      # @return [Occi::Core::Resource] new resource instance
+      def get_resource(resource_type)
+
+        Occi::Log.debug("Instantiating #{resource_type} ...")
+
+        if @model.get_by_id resource_type
+          # we got a resource type identifier
+          Occi::Core::Resource.new resource_type
+        elsif @model.kinds.select { |kind| kind.term == resource_type }.any?
+          # we got a resource type name
+          Occi::Core::Resource.new @model.kinds.select {
+            |kind| kind.term == resource_type
+          }.first.type_identifier
+        else
+          raise "Unknown resource type! [#{resource_type}]"
+        end
+
+      end
+
+      # Retrieves all available resource types.
+      #
+      # @example
+      #    client.get_resource_types # => [ "compute", "storage", "network" ]
+      #
+      # @return [Array<String>] list of available resource types in a human-readable format
+      def get_resource_types
+        Occi::Log.debug("Getting resource types ...")
+        @model.kinds.collect { |kind| kind.term }
+      end
+
+      # Retrieves all available resource type identifiers.
+      #
+      # @example
+      #    client.get_resource_type_identifiers 
+      #    # => [ "http://schemas.ogf.org/occi/infrastructure#compute",
+      #    #      "http://schemas.ogf.org/occi/infrastructure#storage",
+      #    #      "http://schemas.ogf.org/occi/infrastructure#network" ]
+      #
+      # @return [Array<String>] list of available resource types in a Occi ID format
+      def get_resource_type_identifiers
+        Occi::Log.debug("Getting resource identifiers ...")
+        @model.kinds.collect { |kind| kind.type_identifier }
+      end
+
+      # Looks up a mixin using its name and, optionally, a type as well.
+      # Will return mixin's full location (a link) or a description. 
+      #
+      # @example
+      #    client.find_mixin "debian6"
+      #     # => "http://my.occi.service/occi/infrastructure/os_tpl#debian6"
+      #    client.find_mixin "debian6", "os_tpl"
+      #     # => "http://my.occi.service/occi/infrastructure/os_tpl#debian6"
+      #    client.find_mixin "large", "resource_tpl"
+      #     # => "http://my.occi.service/occi/infrastructure/resource_tpl#large"
+      #    client.find_mixin "debian6", "resource_tpl" # => nil
+      #
+      # @param [String] name of the mixin
+      # @param [String] type of the mixin
+      # @param [Boolean] should we describe the mixin or return its link?
+      # @return [String, Occi::Collection, nil] link, mixin description or nothing found
+      def find_mixin(name, type = nil, describe = false)
+
+        Occi::Log.debug("Looking for mixin #{name} + #{type} + #{describe}")
+
+        # is type valid?
+        if type
+          raise "Unknown mixin type! [#{type}]" unless @mixins.has_key? type.to_sym
+        end
+
+        # TODO: extend this code to support multiple matches and regex filters
+        # should we look for links or descriptions?
+        if describe
+          # we are looking for descriptions
+          if type
+            # get the first match from either os_tpls or resource_tpls
+            case
+              when type == "os_tpl"
+                get_os_templates.select { |mixin| mixin.term == name }.first
+              when type == "resource_tpl"
+                get_resource_templates.select { |template| template.term == name }.first
+              else
+                nil
+            end
+          else
+            # try in os_tpls first
+            found = get_os_templates.select { |os| os.term == name }.first
+
+            # then try in resource_tpls
+            found = get_resource_templates.select {
+              |template| template.term == name
+            }.first unless found
+
+            found
+          end
+        else
+          # we are looking for links
+          # prefix mixin name with '#' to simplify the search
+          name = "#" + name
+          if type
+            # return the first match with the selected type
+            @mixins[type.to_sym].select {
+              |mixin| mixin.to_s.reverse.start_with? name.reverse
+            }.first
+          else
+            # there is no type preference, return first global match
+            @mixins.flatten(2).select {
+              |mixin| mixin.to_s.reverse.start_with? name.reverse
+            }.first
+          end
+        end
+      end
+
+      # Retrieves available mixins of a specified type or all available
+      # mixins if the type wasn't specified. Mixins are returned in the
+      # form of mixin identifiers.
+      #
+      # @example
+      #    client.get_mixins
+      #     # => ["http://my.occi.service/occi/infrastructure/os_tpl#debian6",
+      #     #     "http://my.occi.service/occi/infrastructure/resource_tpl#small"]
+      #    client.get_mixins "os_tpl"
+      #     # => ["http://my.occi.service/occi/infrastructure/os_tpl#debian6"]
+      #    client.get_mixins "resource_tpl"
+      #     # => ["http://my.occi.service/occi/infrastructure/resource_tpl#small"]
+      #
+      # @param [String] type of mixins
+      # @return [Array<String>] list of available mixins
+      def get_mixins(type = nil)
+        if type
+          # is type valid?
+          raise "Unknown mixin type! #{type}" unless @mixins.has_key? type.to_sym
+
+          # return mixin of the selected type
+          @mixins[type.to_sym]
+        else
+          # we did not get a type, return all mixins
+          mixins = []
+
+          # flatten the hash and remove its keys
+          get_mixin_types.each do |ltype|
+            mixins.concat @mixins[ltype.to_sym]
+          end
+
+          mixins
+        end
+      end
+
+      # Retrieves available mixin types. Mixin types are presented
+      # in a shortened format (i.e. not as type identifiers).
+      #
+      # @example
+      #    client.get_mixin_types # => [ "os_tpl", "resource_tpl" ]
+      #
+      # @return [Array<String>] list of available mixin types
+      def get_mixin_types
+        @mixins.keys.map! { |k| k.to_s }
+      end
+
+      # Retrieves available mixin type identifiers.
+      #
+      # @example
+      #    client.get_mixin_type_identifiers
+      #     # => ['http://schemas.ogf.org/occi/infrastructure#os_tpl',
+      #     #     'http://schemas.ogf.org/occi/infrastructure#resource_tpl'] 
+      #
+      # @return [Array<String>] list of available mixin type identifiers
+      def get_mixin_type_identifiers
+        identifiers = []
+
+        get_mixin_types.each do |mixin_type|
+          identifiers << 'http://schemas.ogf.org/occi/infrastructure#' + mixin_type
+        end
+
+        identifiers
+      end
+
+      # Retrieves available resources represented by resource locations (URIs).
+      # If no type identifier is specified, all available resource are listed.
+      # Type identifier can be specified in its shortened format (e.g. "compute",
+      # "storage", "network").
+      #
+      # @example
+      #    client.list
+      #     # => [ "http://localhost:3300/compute/jh425jhj3h413-7dj29d7djd9e3-djh2jh4j4j",
+      #     #      "http://localhost:3300/network/kh425jhj3h413-7dj29d7djd9e3-djh2jh4j4j",
+      #     #      "http://localhost:3300/storage/lh425jhj3h413-7dj29d7djd9e3-djh2jh4j4j" ]
+      #    client.list "compute"
+      #     # => [ "http://localhost:3300/compute/jh425jhj3h413-7dj29d7djd9e3-djh2jh4j4j" ]
+      #    client.list "http://schemas.ogf.org/occi/infrastructure#compute"
+      #     # => [ "http://localhost:3300/compute/jh425jhj3h413-7dj29d7djd9e3-djh2jh4j4j" ]
+      #
+      # @param [String] resource type identifier or just type name
+      # @return [Array<String>] list of links
+      def list(resource_type_identifier=nil)
+        if resource_type_identifier
+          # convert type to type identifier
+          resource_type_identifier = @model.kinds.select {
+            |kind| kind.term == resource_type_identifier
+          }.first.type_identifier if @model.kinds.select {
+            |kind| kind.term == resource_type_identifier
+          }.any?
+
+          # check some basic pre-conditions
+          raise "Endpoint is not connected!" unless @connected
+          raise "Unkown resource type identifier! [#{resource_type_identifier}]" unless @model.get_by_id resource_type_identifier
+
+          # split the type identifier and get the most important part
+          uri_part = resource_type_identifier.split('#').last
+
+          # request uri-list from the server
+          path = uri_part + '/'
+        else
+          path = '/'
+        end
+
+        self.class.get(@endpoint + path,
+                       :headers => { "Accept" => 'text/uri-list' }).body.split("\n").compact
+      end
+
+      # Retrieves descriptions for available resources specified by a type
+      # identifier or resource location. If no type identifier or location
+      # is specified, all available resources in all available resource types
+      # will be described. 
+      #
+      # @example
+      #    client.describe
+      #     # => [#<Occi::Collection>, #<Occi::Collection>, #<Occi::Collection>]
+      #    client.describe "compute"
+      #     # => [#<Occi::Collection>, #<Occi::Collection>, #<Occi::Collection>]
+      #    client.describe "http://schemas.ogf.org/occi/infrastructure#compute"
+      #     # => [#<Occi::Collection>, #<Occi::Collection>, #<Occi::Collection>]
+      #    client.describe "http://localhost:3300/compute/j5hk1234jk2524-2j3j2k34jjh234-adfaf1234"
+      #     # => [#<Occi::Collection>]
+      #
+      # @param [String] resource type identifier, type name or resource location
+      # @return [Array<Occi::Collection>] list of resource descriptions
+      def describe(resource_type_identifier=nil)
+
+        # convert type to type identifier
+        resource_type_identifier = @model.kinds.select {
+          |kind| kind.term == resource_type_identifier
+        }.first.type_identifier if @model.kinds.select {
+          |kind| kind.term == resource_type_identifier
+        }.any?
+
+        # check some basic pre-conditions
+        raise "Endpoint is not connected!" unless @connected
+
+        descriptions = []
+
+        if resource_type_identifier.nil?
+          descriptions << get('/')
+        elsif @model.get_by_id resource_type_identifier
+          # we got type identifier
+          # get all available resources of this type
+          locations     = list resource_type_identifier
+
+          # make the requests
+          locations.each do |location|
+            descriptions << get(sanitize_resource_link(location))
+          end
+        elsif resource_type_identifier.start_with? @endpoint
+          # we got resource link
+          # make the request
+          descriptions << get(sanitize_resource_link(resource_type_identifier))
+        else
+          raise "Unkown resource type identifier! [#{resource_type_identifier}]"
+        end
+
+        descriptions
+      end
+
+      # Creates a new resource on the server. Resource must be provided
+      # as an instance of Occi::Core::Entity, e.g. instantiated using
+      # the get_resource method. 
+      #
+      # @example
+      #    res = client.get_resource "compute"
+      #
+      #    res.title = "MyComputeResource1"
+      #    res.mixins << client.find_mixin('small', "resource_tpl")
+      #    res.mixins << client.find_mixin('debian6', "os_tpl")
+      #
+      #    client.create res # => "http://localhost:3300/compute/df7698...f987fa"
+      #
+      # @param [Occi::Core::Entity] resource to be created on the server
+      # @return [String] URI of the new resource
+      def create(entity)
+
+        # check some basic pre-conditions
+        raise "Endpoint is not connected!" unless @connected
+        raise "#{entity} not an entity" unless entity.kind_of? Occi::Core::Entity
+
+        # is this entity valid?
+        entity.model = @model
+        entity.check
+
+        Occi::Log.debug "Entity kind: #{entity.kind}"
+        kind = entity.kind
+        raise "No kind found for #{entity}" unless kind
+
+        # get location for this kind of entity
+        Occi::Log.debug "Kind location: #{entity.kind.location}"
+        location   = kind.location
+        collection = Occi::Collection.new
+
+        # is this entity a Resource or a Link?
+        Occi::Log.debug "Entity class: #{entity.class.name}"
+        collection.resources << entity if entity.kind_of? Occi::Core::Resource
+        collection.links << entity if entity.kind_of? Occi::Core::Link
+
+        # make the request
+        post location, collection
+      end
+
+      # Deploys a compute resource based on an OVF/OVA descriptor available
+      # on a local file system.
+      #
+      # @example
+      #    client.deploy "~/MyVMs/rOcciVM.ovf" # => "http://localhost:3300/compute/343423...42njhdafa"
+      #
+      # @param [String] location of an OVF/OVA file
+      # @return [String] URI of the new resource
+      def deploy(location)
+        media_types = self.class.head(@endpoint).headers['accept'].to_s
+        raise "File #{location} does not exist" unless File.exist? location
+
+        file        = File.read(location)
+
+        if location.include? '.ovf'
+          if media_types.include? 'application/ovf'
+            headers                 = self.class.headers.clone
+            headers['Content-Type'] = 'application/ovf'
+            self.class.post(@endpoint + '/compute/',
+                            :body    => file,
+                            :headers => headers)
+          end
+        elsif location.include? '.ova'
+          if media_types.include? ' application/ova '
+            headers                 = self.class.headers.clone
+            headers['Content-Type'] = 'application/ova'
+            self.class.post(@endpoint + '/compute/',
+                            :body    => file,
+                            :headers => headers)
+          end
+        end
+      end
+
+      # Deletes a resource or all resource of a certain resource type
+      # from the server.
+      #
+      # @example
+      #    client.delete "compute" # => true
+      #    client.delete "http://schemas.ogf.org/occi/infrastructure#compute" # => true
+      #    client.delete "http://localhost:3300/compute/245j42594...98s9df8s9f" # => true 
+      #
+      # @param [String] resource type identifier, type name or location
+      # @return [Boolean] status
+      def delete(resource_type_identifier)
+        # convert type to type identifier
+        raise "Endpoint is not connected!" unless @connected
+
+        path = path_for_resource_type resource_type_identifier
+
+        del path
+      end
+
+      # Triggers given action on a specific resource.
+      #
+      # @example
+      #    TODO: add examples
+      #
+      # @param [String] resource location
+      # @param [String] type of action
+      # @return [String] resource location
+      def trigger(resource_type_identifier, action)
+        # TODO: not tested
+        if @model.kinds.select { |kind| kind.term == resource_type }.any?
+          type_identifier          = @model.kinds.select {
+            |kind| kind.term == resource_type_identifier
+          }.first.type_identifier
+
+          location                 = @model.get_by_id(type_identifier).location
+          resource_type_identifier = @endpoint + location
+        end
+        # check some basic pre-conditions
+        raise "Endpoint is not connected!" unless @connected
+        raise "Unknown resource identifier! #{resource_type_identifier}" unless resource_type_identifier.start_with? @endpoint
+
+        # encapsulate the acion in a collection
+        collection   = Occi::Collection.new
+        scheme, term = action.split(' #')
+        collection.actions << Occi::Core::Action.new(scheme + '#', term)
+
+        # make the request
+        path = sanitize_resource_link(resource_type_identifier) + '?action=' + term
+        post path, collection
+      end
+
+      # Refreshes the Occi::Model used inside the client. Useful for
+      # updating the model without creating a new instance or
+      # reconnecting. Saves a lot of time in an interactive mode.
+      #
+      # @example
+      #    client.refresh
+      def refresh
+        # re-download the model from the server
+        set_model
+      end
+
+      private
+
+      # Sets the logger and log levels. This allows users to pass existing logger
+      # instances to the rOCCI client.
+      #
+      # @example
+      #    set_logger { :out => STDERR, :level => Occi::Log::WARN, :logger => nil }
+      #
+      # @param [Hash] logger options
+      def set_logger(log_options)
+        if log_options[:logger].nil? or (not log_options[:logger].kind_of? Occi::Log)
+          @logger       = Occi::Log.new(log_options[:out])
+          @logger.level = log_options[:level]
+        end
+
+        self.class.debug_output $stderr if log_options[:level] == Occi::Log::DEBUG
+      end
+
+      # Sets auth method and appropriate httparty attributes. Supported auth methods
+      # are: ["basic", "digest", "x509", "none"] 
+      #
+      # @example
+      #    change_auth { :type => "none" }
+      #    change_auth { :type => "basic", :username => "123", :password => "321" }
+      #    change_auth { :type => "digest", :username => "123", :password => "321" }
+      #    change_auth { :type => "x509", :user_cert => "~/cert.pem",
+      #                  :user_cert_password => "321", :ca_path => nil }
+      #    change_auth { :type => "keystone", :token => "005c8a5d7f2c437a9999302c458afbda" }
+      #
+      # @param [Hash] authentication options
+      def change_auth(auth_options)
+        @auth_options = auth_options
+
+        case @auth_options[:type]
+          when "basic"
+            # set up basic auth
+            raise ArgumentError, "Missing required options 'username' and 'password' for basic auth!" unless @auth_options[:username] and @auth_options[:password]
+            self.class.basic_auth @auth_options[:username], @auth_options[:password]
+          when "digest"
+            # set up digest auth
+            raise ArgumentError, "Missing required options 'username' and 'password' for digest auth!" unless @auth_options[:username] and @auth_options[:password]
+            self.class.digest_auth @auth_options[:username], @auth_options[:password]
+          when "x509"
+            # set up pem and optionally pem_password and ssl_ca_path
+            raise ArgumentError, "Missing required option 'user_cert' for x509 auth!" unless @auth_options[:user_cert]
+            raise ArgumentError, "The file specified in 'user_cert' does not exist!" unless File.exists? @auth_options[:user_cert]
+
+            self.class.pem File.read(@auth_options[:user_cert]), @auth_options[:user_cert_password]
+            self.class.ssl_ca_path @auth_options[:ca_path] unless @auth_options[:ca_path].nil?
+            self.class.ssl_ca_file @auth_options[:ca_file] unless @auth_options[:ca_file].nil?
+            self.class.ssl_extra_chain_cert certs_to_file_ary(@auth_options[:proxy_ca]) unless @auth_options[:proxy_ca].nil?
+          when "keystone"
+            # set up OpenStack Keystone token based auth
+            raise ArgumentError, "Missing required option 'token' for OpenStack Keystone auth!" unless @auth_options[:token]
+            self.class.headers['X-Auth-Token'] = @auth_options[:token]
+          when "none", nil
+            # do nothing
+          else
+            raise ArgumentError, "Unknown AUTH method [#{@auth_options[:type]}]!"
+        end
+      end
+
+      # Reads X.509 certificates from a file to an array.
+      #
+      # @example
+      #    certs_to_file_ary "~/.globus/usercert.pem"
+      #      # => [#<String>, #<String>, ...]
+      #
+      # @param [String] Path to a PEM file containing certificates 
+      # @return [Array<String>] An array of read certificates
+      def certs_to_file_ary(ca_file)
+        # TODO: read and separate multiple certificates
+        [] << File.read(ca_file)
+      end
+
+      # Performs GET request and parses the responses to collections.
+      #
+      # @example
+      #    get "/-/" # => #<Occi::Collection>
+      #    get "/compute/" # => #<Occi::Collection>
+      #    get "/compute/fs65g4fs6g-sf54g54gsf-aa12faddf52" # => #<Occi::Collection>
+      #
+      # @param [String] path for the GET request
+      # @param [Occi::Collection] collection of filters
+      # @return [Occi::Collection] parsed result of the request
+      def get(path='', filter=nil)
+        # remove the leading slash
+        path.gsub!(/\A\//, '')
+
+        response = if filter
+                     categories = filter.categories.collect { |category| category.to_text }.join(',')
+                     attributes = filter.entities.collect { |entity| entity.attributes.combine.collect { |k, v| k + '=' + v } }.join(',')
+
+                     headers                 = self.class.headers.clone
+                     headers['Content-Type'] = 'text/occi'
+                     headers['Category'] = categories unless categories.empty?
+                     headers['X-OCCI-Attributes'] = attributes unless attributes.empty?
+
+                     self.class.get(@endpoint + path, :headers => headers)
+                   else
+                     self.class.get(@endpoint + path)
+                   end
+
+        response_msg = response_message response
+        raise "HTTP GET failed! #{response_msg}" unless response.code.between? 200, 300
+
+        Occi::Log.debug "Response location: #{('/' + path).match(/\/.*\//).to_s}"
+        kind = @model.get_by_location(('/' + path).match(/\/.*\//).to_s) if @model
+
+        Occi::Log.debug "Response kind: #{kind}"
+
+        if kind
+          kind.related_to? Occi::Core::Resource ? entity_type = Occi::Core::Resource : entity_type = nil
+          entity_type = Occi::Core::Link if kind.related_to? Occi::Core::Link
+        end
+
+        Occi::Log.debug "Parser call: #{response.content_type} #{entity_type} #{path.include?('-/')}"
+        collection = Occi::Parser.parse(response.content_type, response.body, path.include?('-/'), entity_type, response.headers)
+
+        Occi::Log.debug "Parsed collection: empty? #{collection.empty?}"
+        collection
+      end
+
+      # Performs POST requests and returns URI locations. Resource data must be provided
+      # in an Occi::Collection instance.
+      #
+      # @example
+      #    collection = Occi::Collection.new
+      #    collection.resources << entity if entity.kind_of? Occi::Core::Resource
+      #    collection.links << entity if entity.kind_of? Occi::Core::Link
+      #
+      #    post "/compute/", collection # => "http://localhost:3300/compute/23sf4g65as-asdgsg2-sdfgsf2g"
+      #    post "/network/", collection # => "http://localhost:3300/network/23sf4g65as-asdgsg2-sdfgsf2g"
+      #    post "/storage/", collection # => "http://localhost:3300/storage/23sf4g65as-asdgsg2-sdfgsf2g"
+      #
+      # @param [String] path for the POST request
+      # @param [Occi::Collection] resource data to be POSTed
+      # @return [String] URI location
+      def post(path, collection)
+        # remove the leading slash
+        path.gsub!(/\A\//, '')
+
+        response = if @media_type == 'application/occi+json'
+                     self.class.post(@endpoint + path,
+                                     :body    => collection.to_json,
+                                     :headers => { 'Accept' => 'text/uri-list', 'Content-Type' => 'application/occi+json' })
+                   elsif @media_type == 'text/occi'
+                     self.class.post(@endpoint + path,
+                                     :headers => collection.to_header.merge({ 'Accept' => 'text/uri-list', 'Content-Type' => 'text/occi' }))
+                   else
+                     self.class.post(@endpoint + path,
+                                     :body    => collection.to_text,
+                                     :headers => { 'Accept' => 'text/uri-list', 'Content-Type' => 'text/plain' })
+                   end
+
+        response_msg = response_message response
+        raise "HTTP POST failed! #{response_msg}" unless response.code.between? 200, 300
+
+        URI.parse(response.body).to_s
+      end
+
+      # Performs PUT requests and parses responses to collections.
+      #
+      # @example
+      #    TODO: add examples
+      #
+      # @param [String] path for the PUT request
+      # @param [Occi::Collection] resource data to send
+      # @return [Occi::Collection] parsed result of the request
+      def put(path, collection)
+        # remove the leading slash
+        path.gsub!(/\A\//, '')
+
+        response = if @media_type == 'application/occi+json'
+                     self.class.post(@endpoint + path, :body => collection.to_json, :headers => { 'Content-Type' => 'application/occi+json' })
+                   else
+                     self.class.post(@endpoint + path, { :body => collection.to_text, :headers => { 'Content-Type' => 'text/plain' } })
+                   end
+
+        response_msg = response_message response
+        raise "HTTP PUT failed! #{response_msg}" unless response.code.between? 200, 300
+
+        collection = Occi::Parser.parse(response.content_type, response.body)
+
+        collection
+      end
+
+      # Performs DELETE requests and returns True on success.
+      #
+      # @example
+      #    del "/compute/65sf4g65sf4g-sf6g54sf5g-sfgsf32g3" # => true
+      #
+      # @param [String] path for the DELETE request
+      # @param [Occi::Collection] collection of filters (currently NOT used)
+      # @return [Boolean] status
+      def del(path, filter=nil)
+        # remove the leading slash
+        path.gsub!(/\A\//, '')
+
+        response = self.class.delete(@endpoint + path)
+
+        response_msg = response_message response
+        raise "HTTP DELETE failed! #{response_msg}" unless response.code.between? 200, 300
+
+        true
+      end
+
+      # Creates a link of a specified kind and binds it to the given resource.
+      #
+      # @example
+      #    link_kind = 'http://schemas.ogf.org/occi/infrastructure#storagelink'
+      #    compute = client.get_resource "compute"
+      #    storage_location = "http://localhost:3300/storage/321df21adfad-f3adfa5f4adf-a3d54ffadffe"
+      #    linked_resource_kind = 'http://schemas.ogf.org/occi/infrastructure#storage'
+      #
+      #    link link_kind, compute, storage_location, linked_resource_kind
+      #
+      # @param [String] link type identifier (link kind)
+      # @param [Occi::Core::Resource] resource to link to
+      # @param [URI, String] resource to be linked
+      # @param [String] type identifier of the linked resource
+      # @param [Occi::Core::Attributes] link attributes
+      # @param [Array<String>] link mixins
+      # @return [Occi::Core::Link] link instance 
+      def link(kind, source, target_location, target_kind, attributes=Occi::Core::Attributes.new, mixins=[])
+        link            = Occi::Core::Link.new(kind)
+        link.mixins     = mixins
+        link.attributes = attributes
+        link.target     = (target_location.kind_of? URI::Generic) ? target_location.path : target_location.to_s
+        link.rel        = target_kind
+
+        jj link
+        link.check @model
+        source.links << link
+
+        link
+      end
+
+      # Checks whether the given endpoint URI is valid and adds a trailing
+      # slash if necessary.
+      #
+      # @example 
+      #    prepare_endpoint "http://localhost:3300" # => "http://localhost:3300/"
+      #
+      # @param [String] endpoint URI in a non-canonical string 
+      # @return [String] canonical endpoint URI in a string, with a trailing slash
+      def prepare_endpoint(endpoint)
+        raise 'Endpoint not a valid URI' if (endpoint =~ URI::ABS_URI).nil?
+        @endpoint = endpoint.chomp('/') + '/'
+      end
+
+      # Extracts the resource path from a resource link. It will remove the leading @endpoint
+      # and replace it with a slash.
+      #
+      # @example
+      #    sanitize_resource_link "http://localhost:3300/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
+      #     # => "/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
+      #
+      # @param [String] string containing the full resource link
+      # @return [String] extracted path, with a leading slash
+      def sanitize_resource_link(resource_link)
+        raise "Resource link #{resource_link} is not valid!" unless resource_link.start_with? @endpoint
+
+        resource_link.gsub @endpoint, '/'
+      end
+
+      # @describe find the path for the resource type identifier
+      #
+      # @example
+      #
+      #
+      # @param [String] resource_type_identifier
+      #
+      # @return [String]
+      def path_for_resource_type(resource_type_identifier)
+        if resource_type_identifier.nil? || resource_type_identifier == "/"
+          #we got all
+          path = "/"
+        else
+          kinds = @model.kinds.select { |kind| kind.term == resource_type_identifier }
+          if kinds.any?
+            #we got an type identifier
+            path = "/" + kinds.first.type_identifier.split('#').last + "/"
+          elsif resource_type_identifier.start_with? @endpoint
+            #we got an resource link
+            path = sanitize_resource_link(resource_type_identifier)
+          else
+            raise "Unknown resource identifier! #{resource_type_identifier}"
+          end
+        end
+
+        path
+      end
+
+      # Creates an Occi::Model from data retrieved from the server.
+      #
+      # @example
+      #    set_model
+      def set_model
+
+        #
+        model  = get('/-/')
+        @model = Occi::Model.new(model)
+
+        @mixins = {
+            :os_tpl       => [],
+            :resource_tpl => []
+        }
+
+        #
+        get_os_templates.each do |os_tpl|
+          @mixins[:os_tpl] << os_tpl.type_identifier unless os_tpl.nil? or os_tpl.type_identifier.nil?
+        end
+
+        #
+        get_resource_templates.each do |res_tpl|
+          @mixins[:resource_tpl] << res_tpl.type_identifier unless res_tpl.nil? or res_tpl.type_identifier.nil?
+        end
+      end
+
+      # Retrieves available os_tpls from the model.
+      #
+      # @example
+      #    get_os_templates # => #<Occi::Collection>
+      #
+      # @return [Occi::Collection] collection containing all registered OS templates
+      def get_os_templates
+        @model.get.mixins.select { |mixin| mixin.related.select { |rel| rel.end_with? 'os_tpl' }.any? }
+      end
+
+      # Retrieves available resource_tpls from the model.
+      #
+      # @example
+      #    get_resource_templates # => #<Occi::Collection>
+      #
+      # @return [Occi::Collection] collection containing all registered resource templates
+      def get_resource_templates
+        @model.get.mixins.select { |mixin| mixin.related.select { |rel| rel.end_with? 'resource_tpl' }.any? }
+      end
+
+      # Sets media type. Will choose either application/occi+json or text/plain
+      # based on the formats supported by the server.
+      #
+      # @example
+      #    set_media_type # => 'application/occi+json'
+      #
+      # @return [String] chosen media type
+      def set_media_type
+        media_types = self.class.head(@endpoint).headers['accept']
+        Occi::Log.debug("Available media types: #{media_types}")
+        @media_type = case media_types
+                        when /application\/occi\+json/
+                          'application/occi+json'
+                        else
+                          'text/plain'
+                      end
+      end
+
+      # Generates a human-readable response message based on the HTTP response code. 
+      #
+      # @example
+      #    response_message self.class.delete(@endpoint + path)
+      #     # =>  'HTTP Response status: [200] OK'
+      #
+      # @param [HTTParty::Response] HTTParty response object
+      # @return [String] message
+      def response_message(response)
+        @last_response = response
+        'HTTP Response status: [' + response.code.to_s + '] ' + reason_phrase(response.code)
+      end
+
+      # Converts HTTP response codes to human-readable phrases.
+      #
+      # @example
+      #    reason_phrase(500) # => "Internal Server Error"
+      #
+      # @param [Integer] HTTP response code
+      # @return [String] human-readable phrase
+      def reason_phrase(code)
+        HTTP_CODES[code.to_s]
+      end
+
+    end
+
+    end
+  end
+end