haveapi 0.6.0 → 0.7.0

data/lib/haveapi/client_examples/http.rb

@@ -0,0 +1,91 @@
+require 'pp'
+require 'cgi'
+require 'rack/utils'
+
+module HaveAPI::ClientExamples
+  class Http < HaveAPI::ClientExample
+    label 'HTTP'
+    code :http
+    order 100
+
+    def init
+      <<END
+OPTIONS /v#{version}/ HTTP/1.1
+Host: #{host}
+
+END
+    end
+
+    def auth(method, desc)
+      case method
+      when :basic
+        <<END
+GET / HTTP/1.1
+Host: #{host}
+Authorization: Basic dXNlcjpzZWNyZXQ=
+
+END
+
+      when :token
+        <<END
+POST /_auth/token/tokens HTTP/1.1
+Host: #{host}
+Content-Type: application/json
+
+#{JSON.pretty_generate({token: {login: 'user', password: 'secret', lifetime: 'fixed'}})}
+END
+      end
+    end
+
+    def request(sample)
+      path = resolve_path(
+          action[:method],
+          action[:url],
+          sample[:url_params] || [],
+          sample[:request]
+      )
+
+      req = "#{action[:method]} #{path} HTTP/1.1\n"
+      req << "Host: #{host}\n"
+      req << "Content-Type: application/json\n\n"
+
+      if action[:method] != 'GET' && sample[:request] && !sample[:request].empty?
+        req << JSON.pretty_generate({action[:input][:namespace] => sample[:request]})
+      end
+
+      req
+    end
+
+    def response(sample)
+      content = JSON.pretty_generate({
+          status: sample[:status],
+          message: sample[:message],
+          response: {action[:output][:namespace] => sample[:response]},
+          errors: sample[:errors],
+      })
+
+      status_msg = Rack::Utils::HTTP_STATUS_CODES[sample[:http_status]]
+
+      res = "HTTP/1.1 #{sample[:http_status]} #{status_msg}\n"
+      res << "Content-Type: application/json;charset=utf-8\n"
+      res << "Content-Length: #{content.size}\n\n"
+      res << content
+      res
+    end
+
+    def resolve_path(method, url, url_params, input_params)
+      ret = url.clone
+
+      url_params.each do |v|
+        ret.sub!(/:[a-zA-Z\-_]+/, v.to_s)
+      end
+
+      return ret if method != 'GET' || !input_params || input_params.empty?
+
+      ret << '?'
+      ret << input_params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join('&')
+
+      ret
+    end
+  end
+end

data/lib/haveapi/client_examples/js_client.rb

@@ -0,0 +1,149 @@
+module HaveAPI::ClientExamples
+  class JsClient < HaveAPI::ClientExample
+    label 'JavaScript'
+    code :javascript
+    order 10
+
+    def init
+      <<END
+import HaveAPI from 'haveapi-client'
+
+var api = new HaveAPI.Client("#{base_url}", {version: "#{version}"});
+END
+    end
+
+    def auth(method, desc)
+      case method
+      when :basic
+        <<END
+#{init}
+
+api.authenticate("basic", {
+  username: "user",
+  password: "secret"
+}, function (client, status) {
+  console.log("Authenticated?", status);
+});
+END
+
+      when :token
+        <<END
+#{init}
+
+// Request a new token
+api.authenticate("token", {
+  username: "user",
+  password: "secret"
+}, function (client, status) {
+  console.log("Authenticated?", status);
+
+  if (status)
+    console.log("Token is", client.authProvider.token);
+});
+
+// Use an existing token
+api.authenticate("token", {
+  token: "qwertyuiop..."
+}, function (client, status) {
+  console.log("Authenticated?", status);
+});
+END
+      end
+    end
+
+    def example(sample)
+      args = []
+
+      args.concat(sample[:url_params]) if sample[:url_params]
+
+      if sample[:request] && !sample[:request].empty?
+        args << JSON.pretty_generate(sample[:request])
+      end
+
+      out = "#{init}\n"
+      out << "api.#{resource_path.join('.')}.#{action_name}"
+      out << '('
+      out << "#{args.join(', ')}, " unless args.empty?
+
+      callback = "function (client, reply) {\n"
+      callback << "  console.log('Response', reply);\n"
+
+      if sample[:status]
+        callback << response(sample)
+
+      else
+        callback << error(sample)
+      end
+
+      callback << "}"
+
+      out << callback.strip
+      out << ');'
+      out
+    end
+
+    def response(sample)
+      out = ''
+
+      case action[:output][:layout]
+      when :hash
+        out << "# reply is an instance of HaveAPI.Client.Response\n"
+        out << "# reply.response() returns an object with output parameters:\n"
+        out << JSON.pretty_generate(sample[:response] || {}).split("\n").map do |v|
+          "  // #{v}"
+        end.join("\n")
+
+      when :hash_list
+        out << "# reply is an instance of HaveAPI.Client.Response\n"
+        out << "# reply.response() returns an array of objects:\n"
+        out << JSON.pretty_generate(sample[:response] || []).split("\n").map do |v|
+          "  // #{v}"
+        end.join("\n")
+
+      when :object
+        out << "  // reply is an instance of HaveAPI.Client.ResourceInstance\n"
+
+        (sample[:response] || {}).each do |k, v|
+          param = action[:output][:parameters][k]
+
+          if param[:type] == 'Resource'
+            out << "  // reply.#{k} = HaveAPI.Client.ResourceInstance("
+            out << "resource: #{param[:resource].join('.')}, "
+
+            if v.is_a?(::Hash)
+              out << v.map { |k,v| "#{k}: #{PP.pp(v, '').strip}" }.join(', ')
+            else
+              out << "id: #{v}"
+            end
+
+            out << ")\n"
+
+          elsif param[:type] == 'Custom' && (v.is_a?(::Hash) || v.is_a?(::Array))
+            json = JSON.pretty_generate(v).split("\n").map do |v|
+              "  // #{v}"
+            end.join("\n")
+
+            out << "  // reply.#{k} = #{json}"
+
+          else
+            out << "  // reply.#{k} = #{PP.pp(v, '')}"
+          end
+        end
+
+      when :object_list
+        out << "  // reply is an instance of HaveAPI.Client.ResourceInstanceList\n"
+      end
+
+      out
+
+    end
+
+    def error(sample)
+      out = ''
+      out << "  // reply.isOk() returns false\n"
+      out << "  // reply.message() returns the error message\n"
+      out << "  // reply.envelope.errors contains parameter errors\n"
+      out
+    end
+  end
+end

data/lib/haveapi/client_examples/php_client.rb

@@ -0,0 +1,122 @@
+module HaveAPI::ClientExamples
+  class PhpClient < HaveAPI::ClientExample
+    label 'PHP'
+    code :php
+    order 20
+
+    def init
+      <<END
+$api = new \\HaveAPI\\Client("#{base_url}", "#{version}");
+END
+    end
+
+    def auth(method, desc)
+      case method
+      when :basic
+        <<END
+#{init}
+
+$api->authenticate("basic", ["username" => "user", "password" => "secret"]);
+END
+
+      when :token
+        <<END
+#{init}
+
+// Get token using username and password
+$api->authenticate("token", ["username" => "user", "password" => "secret"]);
+
+echo "Token = ".$api->getAuthenticationProvider()->getToken();
+
+// Next time, the client can authenticate using the token directly
+$api->authenticate("token", ["token" => $savedToken]);
+END
+      end
+    end
+
+    def example(sample)
+      args = []
+
+      args.concat(sample[:url_params]) if sample[:url_params]
+
+      if sample[:request] && !sample[:request].empty?
+        args << format_parameters(:input, sample[:request])
+      end
+
+      out = "#{init}\n"
+      out << "$reply = $api->#{resource_path.join('->')}->#{action_name}"
+      out << "(#{args.join(', ')});\n"
+
+      return (out << response(sample)) if sample[:status]
+
+      out << "// Throws exception \\HaveAPI\\Client\\Exception\\ActionFailed"
+      out
+    end
+
+    def response(sample)
+      out = "\n"
+
+      case action[:output][:layout]
+      when :hash
+        out << "// $reply is an instance of \\HaveAPI\\Client\\Response\n"
+        out << "// $reply->getResponse() returns an associative array of output parameters:\n"
+        out << format_parameters(:output, sample[:response] || {}, "// ")
+
+      when :hash_list
+        out << "// $reply is an instance of \\HaveAPI\\Client\\Response\n"
+        out << "// $reply->getResponse() returns an array of associative arrays:\n"
+
+      when :object
+        out << "// $reply is an instance of \\HaveAPI\\Client\\ResourceInstance\n"
+
+        (sample[:response] || {}).each do |k, v|
+          param = action[:output][:parameters][k]
+
+          if param[:type] == 'Resource'
+            out << "// $reply->#{k} = \\HaveAPI\\Client\\ResourceInstance("
+            out << "resource: #{param[:resource].join('.')}, "
+
+            if v.is_a?(::Hash)
+              out << v.map { |k,v| "#{k}: #{PP.pp(v, '').strip}" }.join(', ')
+            else
+              out << "id: #{v}"
+            end
+
+            out << ")\n"
+
+          elsif param[:type] == 'Custom'
+            out << "// $reply->#{k} is a custom type"
+
+          else
+            out << "// $reply->#{k} = #{PP.pp(v, '')}"
+          end
+        end
+
+      when :object_list
+        out << "// $reply is an instance of \\HaveAPI\\Client\\ResourceInstanceList"
+      end
+
+      out
+    end
+
+    def format_parameters(dir, params, prefix = '')
+      ret = []
+
+      params.each do |k, v|
+        if action[dir][:parameters][k][:type] == 'Custom'
+          ret << "#{prefix}  \"#{k}\" => custom type}"
+
+        else
+          ret << "#{prefix}  \"#{k}\" => #{value(v)}"
+        end
+      end
+
+      "#{prefix}[\n#{ret.join(",\n")}\n#{prefix}]"
+    end
+
+    def value(v)
+      return v if v.is_a?(::Numeric) || v === true || v === false
+      "\"#{v}\""
+    end
+  end
+end

data/lib/haveapi/client_examples/ruby_cli.rb

@@ -0,0 +1,117 @@
+module HaveAPI
+  module CLI ; end
+end
+
+require 'haveapi/cli/output_formatter'
+
+module HaveAPI::ClientExamples
+  class RubyCli < HaveAPI::ClientExample
+    label 'CLI'
+    code :bash
+    order 30
+
+    def init
+      "$ haveapi-cli -u #{base_url} --version #{version}"
+    end
+
+    def auth(method, desc)
+      case method
+      when :basic
+        <<END
+# Provide credentials on command line
+#{init} --auth basic --username user --password secret
+
+# If username or password isn't provided, the user is asked on stdin
+#{init} --auth basic --username user
+Password: secret
+END
+
+      when :token
+        <<END
+# Get token using username and password and save it to disk
+# Note that the client always has to call some action. APIs should provide
+# an action to get information about the current user, so that's what we're
+# calling now.
+#{init} --auth token --username user --save user current
+Password: secret
+
+# Now the token is read from disk and the user does not have to provide username
+# nor password and be authenticated
+#{init} user current
+END
+      end
+    end
+
+    def example(sample)
+      cmd = [init]
+      cmd << resource_path.join('.')
+      cmd << action_name
+      cmd.concat(sample[:url_params]) if sample[:url_params]
+
+      if sample[:request] && !sample[:request].empty?
+        cmd << "-- \\\n"
+
+        res = cmd.join(' ') + sample[:request].map do |k, v|
+          ' '*14 + input_param(k, v)
+        end.join(" \\\n")
+
+      else
+        res = cmd.join(' ')
+      end
+
+      return response(sample, res) if sample[:status]
+
+      res << "\nAction failed: #{sample[:message]}\n"
+
+      if sample[:errors] && sample[:errors].any?
+        res << "Errors:\n"
+        sample[:errors].each do |param, e|
+          res << "\t#{param}: #{e.join('; ')}\n"
+        end
+      end
+
+      res
+    end
+
+    def response(sample, res)
+      return res if sample[:response].nil? || sample[:response].empty?
+
+      cols = []
+
+      action[:output][:parameters].each do |name, param|
+        col = {
+            name: name,
+            align: %w(Integer Float).include?(param[:type]) ? 'right' : 'left',
+            label: param[:label] && !param[:label].empty? ? param[:label] : name.upcase,
+        }
+
+        if param[:type] == 'Resource'
+          col[:display] = Proc.new do |r|
+            next '' unless r
+            next r unless r.is_a?(::Hash)
+
+            "#{r[ param[:value_label].to_sym ]} (##{r[ param[:value_id].to_sym ]})"
+          end
+        end
+
+        cols << col
+      end
+
+      res << "\n" << HaveAPI::CLI::OutputFormatter.format(
+          sample[:response],
+          cols
+      )
+      res
+    end
+
+    def input_param(name, value)
+      option = name.to_s.gsub(/_/, '-')
+
+      if action[:input][:parameters][name][:type] == 'Boolean'
+        return value ? "--#{option}" : "--no-#{name}"
+      end
+
+      "--#{option} '#{value}'"
+    end
+  end
+end