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 +4 -4
- data/CHANGELOG.md +6 -0
- data/README.md +86 -3
- data/lib/reso_web_api/authentication.rb +1 -0
- data/lib/reso_web_api/authentication/simple_token_auth.rb +23 -0
- data/lib/reso_web_api/client.rb +11 -1
- data/lib/reso_web_api/version.rb +1 -1
- data/reso_web_api.gemspec +1 -0
- metadata +17 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 67631df91f672fae2f93f55775fe0428cd9499c2
|
4
|
+
data.tar.gz: ff3124a85d13350d727091124f6b1a26505192ff
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 0ec818165bb57a2aaa96f7648d8926d4d2970f9b44fc7e0f4fb08104507cd42946291e968eb1503c4d06bf9d86ddc46561dba9d37b38cf372c99ae92e53e055c
|
7
|
+
data.tar.gz: 42b196b79c5e818acea12e690a664fc35e51d922c4447d6264b083ddd53f18d9ec20821664cef9476b4c8e13ea94a1eaf4f0b1e91114290087f3a03cd59d99a6
|
data/CHANGELOG.md
CHANGED
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
|
+
[](https://badge.fury.io/rb/reso_web_api)
|
8
|
+
[](https://app.codeship.com/projects/290070)
|
9
|
+
[](https://codeclimate.com/github/wrstudios/reso_web_api/test_coverage)
|
10
|
+
[](https://codeclimate.com/github/wrstudios/reso_web_api/maintainability)
|
11
|
+
[](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
|
-
###
|
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'
|
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
|
@@ -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
|
data/lib/reso_web_api/client.rb
CHANGED
@@ -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
|
-
|
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
|
data/lib/reso_web_api/version.rb
CHANGED
data/reso_web_api.gemspec
CHANGED
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.
|
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-
|
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
|