fmrest 0.18.0 → 0.20.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +8 -0
- data/README.md +65 -91
- metadata +8 -7
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 6c4b366640593f14ee48c1e4443f92aeb68edfe089cad7c7108c27526c1771cc
|
4
|
+
data.tar.gz: 4e772c3d19b64e030e8e572a30ef251715db66f94082ed95becd2d97eed790ae
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 413b4820538640c3c68f2c03cd14e624f4883da55b36810e58d71928d2712b51b6c1a85a93136a53fab695bd02d96ef2cc6d6ad2cf4b7ca63af08cb6957b5dab
|
7
|
+
data.tar.gz: 74b50c3faf532012b775e1dbe21df8a0455d044fcd46cb26213eef21f608d82eed995be9fb941dbebdaf388497ad549ed596fbced218832da0c5f21081b9e1d2
|
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,13 @@
|
|
1
1
|
## Changelog
|
2
2
|
|
3
|
+
### 0.20.0
|
4
|
+
|
5
|
+
* Forward proxy options to AWS Client when using `fmrest-cloud` gem
|
6
|
+
|
7
|
+
### 0.19.0
|
8
|
+
|
9
|
+
* Added native support for FileMaker Cloud through the `fmrest-cloud` gem
|
10
|
+
|
3
11
|
### 0.18.0
|
4
12
|
|
5
13
|
* Better support for portals with mismatching field qualifiers
|
data/README.md
CHANGED
@@ -5,14 +5,30 @@
|
|
5
5
|
[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/beezwax/fmrest-ruby)
|
6
6
|
|
7
7
|
A Ruby client for
|
8
|
-
[FileMaker
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
15
|
-
|
8
|
+
[FileMaker's Data API](https://help.claris.com/en/data-api-guide)
|
9
|
+
with ActiveRecord-ish ORM features.
|
10
|
+
|
11
|
+
While pretty feature-rich, fmrest-ruby doesn't yet support 100% of FileMaker
|
12
|
+
19's Data API features. See the [implementation completeness
|
13
|
+
table](#api-implementation-completeness-table) to check if a feature you need
|
14
|
+
is natively supported by the gem.
|
15
|
+
|
16
|
+
Need Ruby or FileMaker consulting? Contact us at
|
17
|
+
[Beezwax.net](https://beezwax.net/)
|
18
|
+
|
19
|
+
## Contents
|
20
|
+
|
21
|
+
* [Gems](#gems)
|
22
|
+
* [Installation](#installation)
|
23
|
+
* [Simple example](#simple-example)
|
24
|
+
* [Connection settings](#connection-settings)
|
25
|
+
* [Session token store](#session-token-store)
|
26
|
+
* [Date fields and timezones](#date-fields-and-timezones)
|
27
|
+
* [ActiveRecord-like ORM (fmrest-spyke)](#activerecord-like-orm-fmrest-spyke)
|
28
|
+
* [Logging](#logging)
|
29
|
+
* [Gotchas](#gotchas)
|
30
|
+
* [API implementation completeness table](#api-implementation-completeness-table)
|
31
|
+
* [Supported Ruby versions](#supported-ruby-versions)
|
16
32
|
|
17
33
|
## Gems
|
18
34
|
|
@@ -20,28 +36,26 @@ The `fmrest` gem is a wrapper for two other gems:
|
|
20
36
|
|
21
37
|
* `fmrest-spyke`, providing an ActiveRecord-like ORM library built on top
|
22
38
|
of `fmrest-core` and [Spyke](https://github.com/balvig/spyke).
|
23
|
-
* `fmrest-core`, providing the core
|
39
|
+
* `fmrest-core`, providing the core
|
40
|
+
[Faraday](https://github.com/lostisland/faraday) connection builder, session
|
24
41
|
management, and other core utilities.
|
25
42
|
|
43
|
+
In addition, the optional `fmrest-cloud` gem adds support for FileMaker Cloud.
|
44
|
+
See the [main document on connecting to FileMaker
|
45
|
+
Cloud](docs/FileMakerCloud.md).
|
46
|
+
|
26
47
|
## Installation
|
27
48
|
|
28
|
-
|
49
|
+
In your Gemfile:
|
29
50
|
|
30
51
|
```ruby
|
31
52
|
gem 'fmrest'
|
32
|
-
```
|
33
|
-
|
34
|
-
Or if you just want to use the Faraday connection without the ORM features:
|
35
53
|
|
36
|
-
|
37
|
-
gem 'fmrest-
|
54
|
+
# Optional: if your files are hosted on FileMaker Cloud
|
55
|
+
gem 'fmrest-cloud'
|
38
56
|
```
|
39
57
|
|
40
|
-
## Simple
|
41
|
-
|
42
|
-
### ORM example
|
43
|
-
|
44
|
-
Most people would want to use the ORM features:
|
58
|
+
## Simple example
|
45
59
|
|
46
60
|
```ruby
|
47
61
|
# A Layout model connecting to the "Honeybees Web" FileMaker layout
|
@@ -90,32 +104,9 @@ bee.tasks.build(urgency: "Today")
|
|
90
104
|
bee.save
|
91
105
|
```
|
92
106
|
|
93
|
-
|
94
|
-
|
95
|
-
|
96
|
-
Data API interaction and just want a lightweight solution) you can simply use
|
97
|
-
the Faraday connection provided by `fmrest-core`:
|
98
|
-
|
99
|
-
```ruby
|
100
|
-
connection = FmRest::V1.build_connection(
|
101
|
-
host: "…",
|
102
|
-
database: "…",
|
103
|
-
username: "…",
|
104
|
-
password: "…"
|
105
|
-
)
|
106
|
-
|
107
|
-
# Get all records (as parsed JSON)
|
108
|
-
connection.get("layouts/FancyLayout/records")
|
109
|
-
|
110
|
-
# Create new record
|
111
|
-
connection.post do |req|
|
112
|
-
req.url "layouts/FancyLayout/records"
|
113
|
-
|
114
|
-
# You can just pass a hash for the JSON body
|
115
|
-
req.body = { … }
|
116
|
-
end
|
117
|
-
```
|
118
|
-
|
107
|
+
In case you don't want the ORM features (i.e. you only need authentication and
|
108
|
+
JSON parsing, and are comfortable writing the API requests manually without the
|
109
|
+
ORM overhead) you can use the Faraday connection provided by `fmrest-core`.
|
119
110
|
See the [main document on using the base
|
120
111
|
connection](docs/BaseConnectionUsage.md) for more.
|
121
112
|
|
@@ -125,10 +116,6 @@ The minimum required connection settings are `:host`, `:database`, `:username`
|
|
125
116
|
and `:password`, but fmrest-ruby has many other options you can pass when
|
126
117
|
setting up a connection (see [full list](#full-list-of-available-options) below).
|
127
118
|
|
128
|
-
If you're using FileMaker Cloud you may need to pass `:fmid_token` instead
|
129
|
-
of the regular `:username` and `:password`. See the [main document on
|
130
|
-
connecting to FileMaker Cloud](docs/FileMakerCloud.md) for more info.
|
131
|
-
|
132
119
|
`:ssl` and `:proxy` are forwarded to the underlying
|
133
120
|
[Faraday](https://github.com/lostisland/faraday) connection. You can use this
|
134
121
|
to, for instance, disable SSL verification:
|
@@ -153,9 +140,8 @@ Option | Description | Format
|
|
153
140
|
`:username` | A Data API-ready account | String | None
|
154
141
|
`:password` | Your password | String | None
|
155
142
|
`:account_name` | Alias of `:username` | String | None
|
156
|
-
`:fmid_token` | Claris ID token (only needed for FileMaker Cloud) | String | None
|
157
143
|
`:ssl` | SSL options to be forwarded to Faraday | Faraday SSL options | None
|
158
|
-
`:proxy` | Proxy
|
144
|
+
`:proxy` | Proxy URI e.g. `http://username:password@proxy.host:5000` | String / URI | None
|
159
145
|
`:log` | Log JSON responses to STDOUT | Boolean | `false`
|
160
146
|
`:log_level` | Which log level to log into | Values accepted by `Logger#level=` | `:debug`
|
161
147
|
`:coerce_dates` | See section on [date fields](#date-fields-and-timezones) | Boolean \| `:hybrid` \| `:full` | `false`
|
@@ -165,6 +151,11 @@ Option | Description | Format
|
|
165
151
|
`:timezone` | The timezone for the FM server | `:local` \| `:utc` \| `nil` | `nil`
|
166
152
|
`:autologin` | Whether to automatically start Data API sessions | Boolean | `true`
|
167
153
|
`:token` | Used to manually provide a session token (e.g. if `:autologin` is `false`) | String | None
|
154
|
+
`:fmid_token` | Claris ID token (only needed if manually obtaining the token) | String | None
|
155
|
+
`:cloud` | Specifies whether the host is using FileMaker Cloud | `:auto` \| Boolean | `:auto`
|
156
|
+
`:cognito_client_id`| Overwrites the hardcoded FileMaker Cloud Cognito Client ID | String | None
|
157
|
+
`:cognito_pool_id` | Overwrites the hardcoded FileMaker Cloud Cognito Pool ID | String | None
|
158
|
+
`:aws_region` | Overwrites the hardcoded FileMaker Cloud AWS Region | String | None
|
168
159
|
|
169
160
|
### Default connection settings
|
170
161
|
|
@@ -207,7 +198,7 @@ See the [main document on date fields](docs/DateFields.md) for more info.
|
|
207
198
|
## ActiveRecord-like ORM (fmrest-spyke)
|
208
199
|
|
209
200
|
[Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for
|
210
|
-
building REST ORM models. fmrest-ruby
|
201
|
+
building REST ORM models. fmrest-ruby uses it to build its ORM features,
|
211
202
|
bundled in the `fmrest-spyke` gem (already included if you're using the
|
212
203
|
`fmrest` gem).
|
213
204
|
|
@@ -265,39 +256,33 @@ class Honeybee < FmRest::Layout
|
|
265
256
|
end
|
266
257
|
```
|
267
258
|
|
268
|
-
|
269
|
-
connection settings, so you don't have to worry about setting that up.
|
270
|
-
|
271
|
-
Note that these settings are inheritable, so you could create a base class that
|
259
|
+
These settings are class-inheritable, so you could create a base class that
|
272
260
|
does the initial connection setup and then inherit from it in models using that
|
273
261
|
same connection. E.g.:
|
274
262
|
|
275
263
|
```ruby
|
276
|
-
class
|
264
|
+
class ApplicationFmLayout < FmRest::Layout
|
277
265
|
self.fmrest_config = { host: "…", database: "…", … }
|
278
266
|
end
|
279
267
|
|
280
|
-
class Honeybee <
|
281
|
-
# This model will use the same connection as
|
268
|
+
class Honeybee < ApplicationFmLayout
|
269
|
+
# This model will use the same connection as ApplicationFmLayout
|
282
270
|
end
|
283
271
|
```
|
284
272
|
|
285
|
-
|
273
|
+
If `fmrest_config` is not set, your model will try to use
|
286
274
|
`FmRest.default_connection_settings` instead.
|
287
275
|
|
288
276
|
#### Connection settings overlays
|
289
277
|
|
290
278
|
There may be cases where you want to use a different set of connection settings
|
291
|
-
depending on context,
|
292
|
-
|
293
|
-
|
294
|
-
|
295
|
-
the model in one context would also change it in all other contexts, leading to
|
296
|
-
security issues.
|
279
|
+
depending on context. For example, if you want to use username and password
|
280
|
+
provided by the user in a web application. Since `.fmrest_config` is set at the
|
281
|
+
class level, changing the username/password for the model in one context would
|
282
|
+
also change it in all other contexts, leading to security issues.
|
297
283
|
|
298
|
-
To solve this scenario, fmrest-ruby provides a way of defining thread-local
|
299
|
-
reversible connection settings overlays through
|
300
|
-
`.fmrest_config_overlay=`.
|
284
|
+
To solve this scenario, fmrest-ruby provides a way of defining thread-local,
|
285
|
+
reversible connection settings overlays through `.fmrest_config_overlay=`.
|
301
286
|
|
302
287
|
See the [main document on connection setting overlays](docs/ConfigOverlays.md)
|
303
288
|
for details on how it works.
|
@@ -461,12 +446,10 @@ for details.
|
|
461
446
|
|
462
447
|
### Rescuable mixin
|
463
448
|
|
464
|
-
Sometimes you may want to handle Data API errors at the model level. For
|
465
|
-
|
466
|
-
|
467
|
-
|
468
|
-
`Rescuable` that provides convenience macros for that. If you've used Ruby on
|
469
|
-
Rails you may be familiar with its syntax from controllers. E.g.
|
449
|
+
Sometimes you may want to handle Data API errors at the model level. For such
|
450
|
+
cases fmrest-ruby provides an off-by-default mixin called `Rescuable` that
|
451
|
+
provides convenience macros for that. If you've used Ruby on Rails you may be
|
452
|
+
familiar with its syntax from controllers. E.g.
|
470
453
|
|
471
454
|
```ruby
|
472
455
|
class BeeBase < FmRest::Layout
|
@@ -474,9 +457,6 @@ class BeeBase < FmRest::Layout
|
|
474
457
|
|
475
458
|
rescue_from FmRest::APIError::SystemError, with: :notify_admin_of_system_error
|
476
459
|
|
477
|
-
# Shorthand for rescue_with FmRest::APIError::AccountError, ...
|
478
|
-
rescue_account_error { ClarisIDTokenManager.expire_token }
|
479
|
-
|
480
460
|
def self.notify_admin_of_system_error(e)
|
481
461
|
# Shoot an email to the FM admin...
|
482
462
|
end
|
@@ -549,14 +529,14 @@ Read about unexpected scenarios in the [gotchas doc](docs/Gotchas.md).
|
|
549
529
|
|
550
530
|
## API implementation completeness table
|
551
531
|
|
552
|
-
FM Data API reference: https://
|
532
|
+
FM Data API reference: https://help.claris.com/en/data-api-guide/
|
553
533
|
|
554
|
-
| FM
|
534
|
+
| FM 19 Data API feature | Supported by basic connection | Supported by FmRest::Layout |
|
555
535
|
|-------------------------------------|-------------------------------|-----------------------------|
|
556
536
|
| Log in using HTTP Basic Auth | Yes | Yes |
|
557
537
|
| Log in using OAuth | No | No |
|
558
538
|
| Log in to an external data source | No | No |
|
559
|
-
| Log in using Claris ID account
|
539
|
+
| Log in using Claris ID account (FileMaker Cloud) | Yes | Yes |
|
560
540
|
| Log out | Yes | Yes |
|
561
541
|
| Get product information | Manual* | No |
|
562
542
|
| Get database names | Manual* | No |
|
@@ -592,9 +572,9 @@ the following Ruby implementations:
|
|
592
572
|
## Gem development
|
593
573
|
|
594
574
|
After checking out the repo, run `bin/setup` to install dependencies. Then, run
|
595
|
-
`
|
596
|
-
prompt that will allow you to experiment (it will auto-load all
|
597
|
-
spec/fixtures).
|
575
|
+
`bundle exec rspec` to run the specs. You can also run `bin/console` for an
|
576
|
+
interactive prompt that will allow you to experiment (it will auto-load all
|
577
|
+
fixtures in spec/fixtures).
|
598
578
|
|
599
579
|
To install all gems onto your local machine, run
|
600
580
|
`bundle exec rake all:install`. To release a new version, update the version
|
@@ -602,12 +582,6 @@ number in `lib/fmrest/version.rb`, and then run `bundle exec rake all:release`,
|
|
602
582
|
which will create a git tag for the version, push git commits and tags, and
|
603
583
|
push the `.gem` files to [rubygems.org](https://rubygems.org).
|
604
584
|
|
605
|
-
## License
|
606
|
-
|
607
|
-
The gem is available as open source under the terms of the
|
608
|
-
[MIT License](https://opensource.org/licenses/MIT).
|
609
|
-
See [LICENSE.txt](LICENSE.txt).
|
610
|
-
|
611
585
|
## Disclaimer
|
612
586
|
|
613
587
|
This project is not sponsored by or otherwise affiliated with Claris
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: fmrest
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.20.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Pedro Carbajal
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2021-
|
11
|
+
date: 2021-10-26 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: fmrest-core
|
@@ -16,28 +16,28 @@ dependencies:
|
|
16
16
|
requirements:
|
17
17
|
- - '='
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version: 0.
|
19
|
+
version: 0.20.0
|
20
20
|
type: :runtime
|
21
21
|
prerelease: false
|
22
22
|
version_requirements: !ruby/object:Gem::Requirement
|
23
23
|
requirements:
|
24
24
|
- - '='
|
25
25
|
- !ruby/object:Gem::Version
|
26
|
-
version: 0.
|
26
|
+
version: 0.20.0
|
27
27
|
- !ruby/object:Gem::Dependency
|
28
28
|
name: fmrest-spyke
|
29
29
|
requirement: !ruby/object:Gem::Requirement
|
30
30
|
requirements:
|
31
31
|
- - '='
|
32
32
|
- !ruby/object:Gem::Version
|
33
|
-
version: 0.
|
33
|
+
version: 0.20.0
|
34
34
|
type: :runtime
|
35
35
|
prerelease: false
|
36
36
|
version_requirements: !ruby/object:Gem::Requirement
|
37
37
|
requirements:
|
38
38
|
- - '='
|
39
39
|
- !ruby/object:Gem::Version
|
40
|
-
version: 0.
|
40
|
+
version: 0.20.0
|
41
41
|
- !ruby/object:Gem::Dependency
|
42
42
|
name: bundler
|
43
43
|
requirement: !ruby/object:Gem::Requirement
|
@@ -206,7 +206,8 @@ dependencies:
|
|
206
206
|
- - ">="
|
207
207
|
- !ruby/object:Gem::Version
|
208
208
|
version: '0'
|
209
|
-
description: '
|
209
|
+
description: 'FileMaker Data API client with ORM features. This gem is a wrapper for
|
210
|
+
two other gems: fmrest-core and fmrest-spyke.'
|
210
211
|
email:
|
211
212
|
- pedro_c@beezwax.net
|
212
213
|
executables: []
|