Merge branch 'master' into issue#79

Author: kplimack

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2017 SendGrid, Inc.
+Copyright (c) 2016-2018 SendGrid, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,108 @@
+# Usage
+
+Usage examples for SendGrid ruby-http-client
+
+## Initialization
+
+```ruby
+require_relative '../lib/ruby_http_client'
+
+# This uses the SendGrid API as an example
+headers = JSON.parse('
+  {
+    "Authorization": "Bearer ' + ENV['SENDGRID_API_KEY'] + '"
+  }
+')
+host = 'https://api.sendgrid.com'
+client = SendGrid::Client.new(host: host, request_headers: headers)
+```
+
+## Table of Contents
+
+- [GET](#get)
+- [DELETE](#delete)
+- [POST](#post)
+- [PUT](#put)
+- [PATCH](#patch)
+
+## GET
+
+#### GET Collection
+
+```ruby
+query_params = { 'limit' => 100, 'offset' => 0 }
+response = client.version('v3').api_keys.get(query_params: query_params)
+puts response.status_code
+puts response.body
+puts response.headers
+```
+
+#### GET Single
+
+```ruby
+response = client.version('v3').api_keys._(api_key_id).get
+puts response.status_code
+puts response.body
+puts response.headers
+```
+
+## DELETE
+
+```ruby
+response = client.api_keys._(api_key_id).delete
+puts response.status_code
+puts response.headers
+```
+
+## POST
+
+```ruby
+request_body = JSON.parse('
+    {
+        "name": "My API Key Ruby Test",
+        "scopes": [
+            "mail.send",
+            "alerts.create",
+            "alerts.read"
+        ]
+    }
+')
+response = client.version('v3').api_keys.post(request_body: request_body)
+puts response.status_code
+puts response.body
+puts response.headers
+api_key_id = JSON.parse(response.body)['api_key_id']
+```
+
+## PUT
+
+```ruby
+request_body = JSON.parse('
+    {
+        "name": "A New Hope",
+        "scopes": [
+            "user.profile.read",
+            "user.profile.update"
+        ]
+    }
+')
+
+response = client.api_keys._(api_key_id).put(request_body: request_body)
+puts response.status_code
+puts response.body
+puts response.headers
+```
+
+## PATCH
+
+```ruby
+request_body = JSON.parse('
+    {
+        "name": "A New Hope"
+    }
+')
+response = client.api_keys._(api_key_id).patch(request_body: request_body)
+puts response.status_code
+puts response.body
+puts response.headers
+```

USAGE.md

@@ -15,6 +15,19 @@
 #                               request_headers: headers,
 #                               http_options: {open_timeout: 15, read_timeout: 30})
 
+# If you want to make request via proxy, you can set your proxy server in two ways.
+#
+# (1) Pass proxy_options hash
+#
+# client = SendGrid::Client.new(host: host,
+#                               request_headers: headers,
+#                               proxy_options: { host: '127.0.0.1', port: 8080 })
+#
+# (2) Set 'http_proxy' environment variable
+#
+# ENV['http_proxy'] = 'user:[email protected]:8080'
+# client = SendGrid::Client.new(host: host, request_headers: headers)
+
 # GET Collection
 query_params = { 'limit' => 100, 'offset' => 0 }
 response = client.version('v3').api_keys.get(query_params: query_params)

examples/example.rb

@@ -35,8 +35,10 @@ class Client
     #                  Or just pass the version as part of the URL
     #                  (e.g. client._("/v3"))
     #   - +url_path+ -> A list of the url path segments
+    #   - +proxy_options+ -> A hash of proxy settings.
+    #                        (e.g. { host: '127.0.0.1', port: 8080 })
     #
-    def initialize(host: nil, request_headers: nil, version: nil, url_path: nil, http_options: {})
+    def initialize(host: nil, request_headers: nil, version: nil, url_path: nil, http_options: {}, proxy_options: {})
       @host = host
       @request_headers = request_headers || {}
       @version = version
@@ -45,6 +47,7 @@ def initialize(host: nil, request_headers: nil, version: nil, url_path: nil, htt
       @query_params = nil
       @request_body = nil
       @http_options = http_options
+      @proxy_options = proxy_options
     end
 
     # Update the headers for the request
@@ -139,7 +142,7 @@ def build_url(query_params: nil)
     def build_request(name, args)
       build_args(args) if args
       uri = build_url(query_params: @query_params)
-      @http = add_ssl(Net::HTTP.new(uri.host, uri.port))
+      @http = build_http(uri.host, uri.port)
       net_http = Kernel.const_get('Net::HTTP::' + name.to_s.capitalize)
       @request = build_request_headers(net_http.new(uri.request_uri))
       if @request_body &&
@@ -173,6 +176,16 @@ def make_request(http, request)
       Response.new(response)
     end
 
+    # Build HTTP request object
+    #
+    # * *Returns* :
+    #   - Request object
+    def build_http(host, port)
+      params = [host, port]
+      params = params + @proxy_options.values_at(:host, :port, :user, :pass) unless @proxy_options.empty?
+      add_ssl(Net::HTTP.new(*params))
+    end
+
     # Allow for https calls
     #
     # * *Args*    :

lib/ruby_http_client.rb

@@ -185,14 +185,46 @@ def test_http_options
     assert_equal(['test'], url1.url_path)
   end
 
-  def test_docker_exists
-    assert(File.file?('./Dockerfile') || File.file?('./docker/Dockerfile'))
+  def test_proxy_options
+    proxy_options = {
+      host: '127.0.0.1', port: 8080, user: 'anonymous', pass: 'secret'
+    }
+    client = MockRequest.new(
+      host: 'https://api.sendgrid.com',
+      request_headers: { 'Authorization' => 'Bearer xxx' },
+      proxy_options: proxy_options
+    ).version('v3').api_keys
+
+    assert(client.proxy_address, '127.0.0.1')
+    assert(client.proxy_pass, 'secret')
+    assert(client.proxy_port, 8080)
+    assert(client.proxy_user, 'anonymous')
   end
 
-  def test_docker_compose_exists
-    assert(File.file?('./docker-compose.yml') || File.file?('./docker/docker-compose.yml'))
+  def test_proxy_from_http_proxy_environment_variable
+    ENV['http_proxy'] = 'anonymous:[email protected]:8080'
+
+    client = MockRequest.new(
+      host: 'https://api.sendgrid.com',
+      request_headers: { 'Authorization' => 'Bearer xxx' }
+    ).version('v3').api_keys
+
+    assert(client.proxy_address, '127.0.0.1')
+    assert(client.proxy_pass, 'secret')
+    assert(client.proxy_port, 8080)
+    assert(client.proxy_user, 'anonymous')
+  ensure
+    ENV.delete('http_proxy')
   end
 
+  # def test_docker_exists
+  #   assert(File.file?('./Dockerfile') || File.file?('./docker/Dockerfile'))
+  # end
+
+  # def test_docker_compose_exists
+  #   assert(File.file?('./docker-compose.yml') || File.file?('./docker/docker-compose.yml'))
+  # end
+
   def test_env_sample_exists
     assert(File.file?('./.env_sample'))
   end
@@ -241,10 +273,6 @@ def test_troubleshooting_exists
     assert(File.file?('./TROUBLESHOOTING.md'))
   end
 
-  def test_usage_exists
-    assert(File.file?('./USAGE.md'))
-  end
-
   def test_use_cases_exists
     assert(File.file?('./USE_CASES.md'))
   end

test/test_ruby_http_client.rb

@@ -0,0 +1,3 @@
+This directory provides examples for specific use cases. Please [open an issue](https://github.com/sendgrid/ruby-http-client/issues) or make a pull request for any use cases you would like us to document here. Thank you!
+
+ # Table of Contents