reso_web_api 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 4476a6c7c91ca11a6ee826b17173fb7f05875f9a
4
- data.tar.gz: b926a43a312ee862f0139729cac0893bfbba53ac
3
+ metadata.gz: 67631df91f672fae2f93f55775fe0428cd9499c2
4
+ data.tar.gz: ff3124a85d13350d727091124f6b1a26505192ff
5
5
  SHA512:
6
- metadata.gz: f97635ef226ae6e694a5dacf135fac8c43b78b87af4b3c05659b07c2380e991a3866fe9b90b30c72ab9782f584da007052e8070751a5cc9f84aa26fd27e821a2
7
- data.tar.gz: 944f6747aebf0ec3862548c919f79bf15b826a714d71451e12402bd1ed9205a783ca7c2ba07f7b5660f60c393623e3ca99362990108a6b5f39127c4c1e75344e
6
+ metadata.gz: 0ec818165bb57a2aaa96f7648d8926d4d2970f9b44fc7e0f4fb08104507cd42946291e968eb1503c4d06bf9d86ddc46561dba9d37b38cf372c99ae92e53e055c
7
+ data.tar.gz: 42b196b79c5e818acea12e690a664fc35e51d922c4447d6264b083ddd53f18d9ec20821664cef9476b4c8e13ea94a1eaf4f0b1e91114290087f3a03cd59d99a6
data/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # CHANGELOG
2
2
 
3
+ ## 0.2.1
4
+
5
+ * Added `SimpleTokenAuth` strategy for using basic non-expiring, non-refreshable tokens
6
+ * Share logger with OData service
7
+ * Allow passing options to OData service
8
+
3
9
  ## 0.2.0
4
10
 
5
11
  * Refactored code and simplified design
data/README.md CHANGED
@@ -4,6 +4,12 @@ A Ruby library to connects to MLS servers conforming to the [RESO Web API][reso-
4
4
 
5
5
  [reso-web-api]: https://www.reso.org/reso-web-api/
6
6
 
7
+ [![Gem Version](https://badge.fury.io/rb/reso_web_api.svg)](https://badge.fury.io/rb/reso_web_api)
8
+ [![Build Status](https://app.codeship.com/projects/c9f88f50-3a07-0136-6878-6eab29180a68/status?branch=master)](https://app.codeship.com/projects/290070)
9
+ [![Test Coverage](https://api.codeclimate.com/v1/badges/6e707a367bfdd609fc76/test_coverage)](https://codeclimate.com/github/wrstudios/reso_web_api/test_coverage)
10
+ [![Maintainability](https://api.codeclimate.com/v1/badges/6e707a367bfdd609fc76/maintainability)](https://codeclimate.com/github/wrstudios/reso_web_api/maintainability)
11
+ [![Documentation](http://inch-ci.org/github/wrstudios/reso_web_api.png?branch=master)](http://www.rubydoc.info/github/wrstudios/reso_web_api/master)
12
+
7
13
  ## Installation
8
14
 
9
15
  Add this line to your application's Gemfile:
@@ -22,14 +28,23 @@ Or install it yourself as:
22
28
 
23
29
  ## Usage
24
30
 
25
- ### Authentication
31
+ ### Quickstart
26
32
 
27
33
  Instantiating an API client requires two things: an endpoint (i.e. service URL) and an authentication strategy.
28
- You may either instantiate the auth strategy directly and pass it to the client constructor (in the `:auth` parameter), or you may choose to pass a nested hash with options for configuring the strategy instead, as below:
29
34
 
30
35
  ```ruby
31
36
  require 'reso_web_api'
32
37
 
38
+ client = ResoWebApi::Client.new(endpoint: '<Service URL>', auth: auth)
39
+ ```
40
+
41
+ The `:endpoint` option should need no further explanation, for `:auth`, read on below.
42
+
43
+ ### Authentication
44
+
45
+ You may either instantiate the auth strategy directly and pass it to the client constructor (in the `:auth` parameter), or you may choose to pass a nested hash with options for configuring the strategy instead, as below:
46
+
47
+ ```ruby
33
48
  client = ResoWebApi::Client.new(
34
49
  endpoint: 'https://api.my-mls.org/RESO/OData/',
35
50
  auth: {
@@ -45,6 +60,18 @@ end
45
60
  Note that if you choose this option, you _may_ specify the strategy implementation by passing its _class_ as the `:strategy` option.
46
61
  If you omit the `:strategy` parameter, it will default to `ResoWebApi::Authentication::TokenAuth`.
47
62
 
63
+ For a list of available authentication strategies and usage examples, please [see below](#authentication-strategies).
64
+
65
+ ### Advanced Configuration
66
+
67
+ The client is designed to work out-of-the-box and require as little configuration as possible (only endpoint and auth by default).
68
+ However, if you need more control, there are several additional settings that can be configured using the constructor.
69
+
70
+ - `:user_agent`: Sets the `User-Agent` header sent to the service (defaults to `Reso Web API Ruby Gem $VERSION`)
71
+ - `:adapter`: Sets the Faraday adapter used for the connection (defaults to `Net::HTTP`)
72
+ - `:logger`: You may pass your own logger to a client instance. By default, each instance will use the global logger defined on the `ResoWebApi` module, which logs to STDOUT. You can also change the logger on the module itself, which will then be used for all new client instances you create.
73
+ - `:odata`: If you need to pass any special options to the OData service, you may do so here.
74
+
48
75
  ### Accessing Data
49
76
 
50
77
  #### Standard Resources
@@ -70,7 +97,63 @@ The following methods are provided:
70
97
  Other resources may be access using the `#resources` method on the client, which may be accessed as a hash like this:
71
98
 
72
99
  ```ruby
73
- client.resources['OpenHouse'].first # Access the 'OpenHouse' collectionh
100
+ client.resources['OpenHouse'].first # Access the 'OpenHouse' collection
101
+ ```
102
+
103
+ ## Authentication Strategies
104
+
105
+ Since the details of authentication may vary from vendor to vendor, this gem attempts to stay flexible by providing a modular authentication system.
106
+
107
+ ### Available Strategies
108
+
109
+ Currently, we provide the following authentication strategies:
110
+
111
+ #### `SimpleTokenAuth`
112
+
113
+ A simple strategy that works with a static access token. Often used for development access, where security is not a major concern.
114
+
115
+ ##### Configuration
116
+
117
+ - `access_token`: The access token value (`String`).
118
+ - `token_type`: The token type (`String`, optional). Defaults to `Bearer`.
119
+
120
+ ##### Example
121
+
122
+ ```ruby
123
+ client = ResoWebApi::Client.new(
124
+ endpoint: 'https://api.my-mls.org/RESO/OData/',
125
+ auth: {
126
+ strategy: ResoWebApi::Authentication::SimpleTokenAuth,
127
+ access_token: 'abcdefg01234567890'
128
+ }
129
+ )
130
+ ```
131
+
132
+ #### `TokenAuth`
133
+
134
+ A basic OAuth-based token strategy, where a Client ID/Secret pair is sent to a server in exchange for a temporary access token. Frequently used in production systems for its increased security over the static token strategy.
135
+
136
+ ##### Configuration
137
+
138
+ - `endpoint`: The URL of the token server (`String`).
139
+ - `client_id`: The Client ID (`String`).
140
+ - `client_secret`: The Client Secret (`String`).
141
+ - `scope`: The scope for the token (`String`).
142
+ - `grant_type`: The grant type (`String`, optional). Defaults to `client_credentials`.
143
+
144
+ ##### Example
145
+
146
+ ```ruby
147
+ client = ResoWebApi::Client.new(
148
+ endpoint: 'https://api.my-mls.org/RESO/OData/',
149
+ auth: {
150
+ strategy: ResoWebApi::Authentication::TokenAuth,
151
+ endpoint: 'https://oauth.my-mls.org/connect/token',
152
+ client_id: 'deadbeef',
153
+ client_secret: 'T0pS3cr3t',
154
+ scope: 'odata'
155
+ }
156
+ end
74
157
  ```
75
158
 
76
159
  ## Development
@@ -1,4 +1,5 @@
1
1
  require_relative 'authentication/access'
2
2
  require_relative 'authentication/auth_strategy'
3
3
  require_relative 'authentication/middleware'
4
+ require_relative 'authentication/simple_token_auth'
4
5
  require_relative 'authentication/token_auth'
@@ -0,0 +1,23 @@
1
+ module ResoWebApi
2
+ module Authentication
3
+ # A simple auth strategy that uses a static, non-expiring token.
4
+ class SimpleTokenAuth < AuthStrategy
5
+ # The access token (String)
6
+ option :access_token
7
+ # The token type (String, defaults to `Bearer`)
8
+ option :token_type, default: proc { 'Bearer' }
9
+ # This strategy does not require an endpoint
10
+ option :endpoint, optional: true
11
+
12
+ # Simply returns a static, never expiring access token
13
+ # @return [Access] The access token object
14
+ def authenticate
15
+ Access.new(
16
+ 'access_token' => access_token,
17
+ 'token_type' => token_type,
18
+ 'expires_in' => 1 << (1.size * 8 - 2) - 1 # Max int value
19
+ )
20
+ end
21
+ end
22
+ end
23
+ end
@@ -7,7 +7,10 @@ module ResoWebApi
7
7
  class Client < BaseClient
8
8
  include Resources
9
9
 
10
+ # Auth strategy (class instance or Hash)
10
11
  option :auth
12
+ # Options for OData service
13
+ option :odata, optional: true
11
14
 
12
15
  def initialize(options = {})
13
16
  super(options)
@@ -34,7 +37,14 @@ module ResoWebApi
34
37
  # authenticated and authorized connection
35
38
  # @return [OData4::Service] The service instance.
36
39
  def service
37
- @service ||= OData4::Service.new(connection)
40
+ # puts odata, service_options
41
+ @service ||= OData4::Service.new(connection, service_options)
42
+ end
43
+
44
+ # Returns the default options used by the by the OData service
45
+ # @return [Hash] The options hash
46
+ def service_options
47
+ @service_options ||= { logger: logger }.merge(odata || {})
38
48
  end
39
49
 
40
50
  private
@@ -1,3 +1,3 @@
1
1
  module ResoWebApi
2
- VERSION = "0.2.0"
2
+ VERSION = "0.2.1"
3
3
  end
data/reso_web_api.gemspec CHANGED
@@ -28,4 +28,5 @@ Gem::Specification.new do |spec|
28
28
  spec.add_development_dependency "bundler", "~> 1.16"
29
29
  spec.add_development_dependency "rake", "~> 10.0"
30
30
  spec.add_development_dependency "rspec", "~> 3.0"
31
+ spec.add_development_dependency "simplecov", "~> 0.15"
31
32
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: reso_web_api
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.2.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Christoph Wagner
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2018-05-15 00:00:00.000000000 Z
11
+ date: 2018-05-22 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: faraday
@@ -94,6 +94,20 @@ dependencies:
94
94
  - - "~>"
95
95
  - !ruby/object:Gem::Version
96
96
  version: '3.0'
97
+ - !ruby/object:Gem::Dependency
98
+ name: simplecov
99
+ requirement: !ruby/object:Gem::Requirement
100
+ requirements:
101
+ - - "~>"
102
+ - !ruby/object:Gem::Version
103
+ version: '0.15'
104
+ type: :development
105
+ prerelease: false
106
+ version_requirements: !ruby/object:Gem::Requirement
107
+ requirements:
108
+ - - "~>"
109
+ - !ruby/object:Gem::Version
110
+ version: '0.15'
97
111
  description: Allows communication with MLS systems conforming to the RESO Web API
98
112
  standard
99
113
  email:
@@ -118,6 +132,7 @@ files:
118
132
  - lib/reso_web_api/authentication/access.rb
119
133
  - lib/reso_web_api/authentication/auth_strategy.rb
120
134
  - lib/reso_web_api/authentication/middleware.rb
135
+ - lib/reso_web_api/authentication/simple_token_auth.rb
121
136
  - lib/reso_web_api/authentication/token_auth.rb
122
137
  - lib/reso_web_api/base_client.rb
123
138
  - lib/reso_web_api/client.rb