fmrest-spyke 0.18.0 → 0.19.0.rc1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +4 -0
- data/README.md +61 -90
- metadata +6 -6
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: eb879437821941e732a5e52b01c7f0feace73cd3faf1d1e584e0a1a5b3224876
|
4
|
+
data.tar.gz: 02b666bdba2e9a29fcfdea4c34bb6ea26eccaead15b3294de57fc5a000cfc13d
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: bc1506322c774bd2d1bee6a072644df4f37f9116940f710adc6f0fdb9dd4982e9ba570e4f21ee95543d0f52d3e3532ea133dc9a5689621945179eaba33052c28
|
7
|
+
data.tar.gz: d7370baeaf5a4b92ac6b3800ea8fe0ade0525f196cabd2a41615e9cf358251b1cfef2e7263e688545b727f619f6de1802c9f23cde012627e81f1ca5852a6b3e8
|
data/CHANGELOG.md
CHANGED
data/README.md
CHANGED
@@ -5,14 +5,27 @@
|
|
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
|
+
## Contents
|
17
|
+
|
18
|
+
* [Gems](#gems)
|
19
|
+
* [Installation](#installation)
|
20
|
+
* [Simple example](#simple-example)
|
21
|
+
* [Connection settings](#connection-settings)
|
22
|
+
* [Session token store](#session-token-store)
|
23
|
+
* [Date fields and timezones](#date-fields-and-timezones)
|
24
|
+
* [ActiveRecord-like ORM (fmrest-spyke)](#activerecord-like-orm--fmrest-spyke-)
|
25
|
+
* [Logging](#logging)
|
26
|
+
* [Gotchas](#gotchas)
|
27
|
+
* [API implementation completeness table](#api-implementation-completeness-table)
|
28
|
+
* [Supported Ruby versions](#supported-ruby-versions)
|
16
29
|
|
17
30
|
## Gems
|
18
31
|
|
@@ -20,28 +33,26 @@ The `fmrest` gem is a wrapper for two other gems:
|
|
20
33
|
|
21
34
|
* `fmrest-spyke`, providing an ActiveRecord-like ORM library built on top
|
22
35
|
of `fmrest-core` and [Spyke](https://github.com/balvig/spyke).
|
23
|
-
* `fmrest-core`, providing the core
|
36
|
+
* `fmrest-core`, providing the core
|
37
|
+
[Faraday](https://github.com/lostisland/faraday) connection builder, session
|
24
38
|
management, and other core utilities.
|
25
39
|
|
40
|
+
In addition, the optional `fmrest-cloud` gem adds support for FileMaker Cloud.
|
41
|
+
See the [main document on connecting to FileMaker
|
42
|
+
Cloud](docs/FileMakerCloud.md).
|
43
|
+
|
26
44
|
## Installation
|
27
45
|
|
28
|
-
|
46
|
+
In your Gemfile:
|
29
47
|
|
30
48
|
```ruby
|
31
49
|
gem 'fmrest'
|
32
|
-
```
|
33
|
-
|
34
|
-
Or if you just want to use the Faraday connection without the ORM features:
|
35
50
|
|
36
|
-
|
37
|
-
gem 'fmrest-
|
51
|
+
# Optional: if your files are hosted on FileMaker Cloud
|
52
|
+
gem 'fmrest-cloud'
|
38
53
|
```
|
39
54
|
|
40
|
-
## Simple
|
41
|
-
|
42
|
-
### ORM example
|
43
|
-
|
44
|
-
Most people would want to use the ORM features:
|
55
|
+
## Simple example
|
45
56
|
|
46
57
|
```ruby
|
47
58
|
# A Layout model connecting to the "Honeybees Web" FileMaker layout
|
@@ -90,32 +101,9 @@ bee.tasks.build(urgency: "Today")
|
|
90
101
|
bee.save
|
91
102
|
```
|
92
103
|
|
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
|
-
|
104
|
+
In case you don't want the ORM features (i.e. you only need authentication and
|
105
|
+
JSON parsing, and are comfortable writing the API requests manually without the
|
106
|
+
ORM overhead) you can use the Faraday connection provided by `fmrest-core`.
|
119
107
|
See the [main document on using the base
|
120
108
|
connection](docs/BaseConnectionUsage.md) for more.
|
121
109
|
|
@@ -125,10 +113,6 @@ The minimum required connection settings are `:host`, `:database`, `:username`
|
|
125
113
|
and `:password`, but fmrest-ruby has many other options you can pass when
|
126
114
|
setting up a connection (see [full list](#full-list-of-available-options) below).
|
127
115
|
|
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
116
|
`:ssl` and `:proxy` are forwarded to the underlying
|
133
117
|
[Faraday](https://github.com/lostisland/faraday) connection. You can use this
|
134
118
|
to, for instance, disable SSL verification:
|
@@ -153,7 +137,6 @@ Option | Description | Format
|
|
153
137
|
`:username` | A Data API-ready account | String | None
|
154
138
|
`:password` | Your password | String | None
|
155
139
|
`:account_name` | Alias of `:username` | String | None
|
156
|
-
`:fmid_token` | Claris ID token (only needed for FileMaker Cloud) | String | None
|
157
140
|
`:ssl` | SSL options to be forwarded to Faraday | Faraday SSL options | None
|
158
141
|
`:proxy` | Proxy options to be forwarded to Faraday | Faraday proxy options | None
|
159
142
|
`:log` | Log JSON responses to STDOUT | Boolean | `false`
|
@@ -165,6 +148,11 @@ Option | Description | Format
|
|
165
148
|
`:timezone` | The timezone for the FM server | `:local` \| `:utc` \| `nil` | `nil`
|
166
149
|
`:autologin` | Whether to automatically start Data API sessions | Boolean | `true`
|
167
150
|
`:token` | Used to manually provide a session token (e.g. if `:autologin` is `false`) | String | None
|
151
|
+
`:fmid_token` | Claris ID token (only needed if manually obtaining the token) | String | None
|
152
|
+
`:cloud` | Specifies whether the host is using FileMaker Cloud | `:auto` \| Boolean | `:auto`
|
153
|
+
`:cognito_client_id`| Overwrites the hardcoded FileMaker Cloud Cognito Client ID | String | None
|
154
|
+
`:cognito_pool_id` | Overwrites the hardcoded FileMaker Cloud Cognito Pool ID | String | None
|
155
|
+
`:aws_region` | Overwrites the hardcoded FileMaker Cloud AWS Region | String | None
|
168
156
|
|
169
157
|
### Default connection settings
|
170
158
|
|
@@ -207,7 +195,7 @@ See the [main document on date fields](docs/DateFields.md) for more info.
|
|
207
195
|
## ActiveRecord-like ORM (fmrest-spyke)
|
208
196
|
|
209
197
|
[Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for
|
210
|
-
building REST ORM models. fmrest-ruby
|
198
|
+
building REST ORM models. fmrest-ruby uses it to build its ORM features,
|
211
199
|
bundled in the `fmrest-spyke` gem (already included if you're using the
|
212
200
|
`fmrest` gem).
|
213
201
|
|
@@ -265,39 +253,33 @@ class Honeybee < FmRest::Layout
|
|
265
253
|
end
|
266
254
|
```
|
267
255
|
|
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
|
256
|
+
These settings are class-inheritable, so you could create a base class that
|
272
257
|
does the initial connection setup and then inherit from it in models using that
|
273
258
|
same connection. E.g.:
|
274
259
|
|
275
260
|
```ruby
|
276
|
-
class
|
261
|
+
class ApplicationFmLayout < FmRest::Layout
|
277
262
|
self.fmrest_config = { host: "…", database: "…", … }
|
278
263
|
end
|
279
264
|
|
280
|
-
class Honeybee <
|
281
|
-
# This model will use the same connection as
|
265
|
+
class Honeybee < ApplicationFmLayout
|
266
|
+
# This model will use the same connection as ApplicationFmLayout
|
282
267
|
end
|
283
268
|
```
|
284
269
|
|
285
|
-
|
270
|
+
If `fmrest_config` is not set, your model will try to use
|
286
271
|
`FmRest.default_connection_settings` instead.
|
287
272
|
|
288
273
|
#### Connection settings overlays
|
289
274
|
|
290
275
|
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.
|
276
|
+
depending on context. For example, if you want to use username and password
|
277
|
+
provided by the user in a web application. Since `.fmrest_config` is set at the
|
278
|
+
class level, changing the username/password for the model in one context would
|
279
|
+
also change it in all other contexts, leading to security issues.
|
297
280
|
|
298
|
-
To solve this scenario, fmrest-ruby provides a way of defining thread-local
|
299
|
-
reversible connection settings overlays through
|
300
|
-
`.fmrest_config_overlay=`.
|
281
|
+
To solve this scenario, fmrest-ruby provides a way of defining thread-local,
|
282
|
+
reversible connection settings overlays through `.fmrest_config_overlay=`.
|
301
283
|
|
302
284
|
See the [main document on connection setting overlays](docs/ConfigOverlays.md)
|
303
285
|
for details on how it works.
|
@@ -461,12 +443,10 @@ for details.
|
|
461
443
|
|
462
444
|
### Rescuable mixin
|
463
445
|
|
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.
|
446
|
+
Sometimes you may want to handle Data API errors at the model level. For such
|
447
|
+
cases fmrest-ruby provides an off-by-default mixin called `Rescuable` that
|
448
|
+
provides convenience macros for that. If you've used Ruby on Rails you may be
|
449
|
+
familiar with its syntax from controllers. E.g.
|
470
450
|
|
471
451
|
```ruby
|
472
452
|
class BeeBase < FmRest::Layout
|
@@ -474,9 +454,6 @@ class BeeBase < FmRest::Layout
|
|
474
454
|
|
475
455
|
rescue_from FmRest::APIError::SystemError, with: :notify_admin_of_system_error
|
476
456
|
|
477
|
-
# Shorthand for rescue_with FmRest::APIError::AccountError, ...
|
478
|
-
rescue_account_error { ClarisIDTokenManager.expire_token }
|
479
|
-
|
480
457
|
def self.notify_admin_of_system_error(e)
|
481
458
|
# Shoot an email to the FM admin...
|
482
459
|
end
|
@@ -549,14 +526,14 @@ Read about unexpected scenarios in the [gotchas doc](docs/Gotchas.md).
|
|
549
526
|
|
550
527
|
## API implementation completeness table
|
551
528
|
|
552
|
-
FM Data API reference: https://
|
529
|
+
FM Data API reference: https://help.claris.com/en/data-api-guide/
|
553
530
|
|
554
|
-
| FM
|
531
|
+
| FM 19 Data API feature | Supported by basic connection | Supported by FmRest::Layout |
|
555
532
|
|-------------------------------------|-------------------------------|-----------------------------|
|
556
533
|
| Log in using HTTP Basic Auth | Yes | Yes |
|
557
534
|
| Log in using OAuth | No | No |
|
558
535
|
| Log in to an external data source | No | No |
|
559
|
-
| Log in using Claris ID account
|
536
|
+
| Log in using Claris ID account (FileMaker Cloud) | Yes | Yes |
|
560
537
|
| Log out | Yes | Yes |
|
561
538
|
| Get product information | Manual* | No |
|
562
539
|
| Get database names | Manual* | No |
|
@@ -592,9 +569,9 @@ the following Ruby implementations:
|
|
592
569
|
## Gem development
|
593
570
|
|
594
571
|
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).
|
572
|
+
`bundle exec rspec` to run the specs. You can also run `bin/console` for an
|
573
|
+
interactive prompt that will allow you to experiment (it will auto-load all
|
574
|
+
fixtures in spec/fixtures).
|
598
575
|
|
599
576
|
To install all gems onto your local machine, run
|
600
577
|
`bundle exec rake all:install`. To release a new version, update the version
|
@@ -602,12 +579,6 @@ number in `lib/fmrest/version.rb`, and then run `bundle exec rake all:release`,
|
|
602
579
|
which will create a git tag for the version, push git commits and tags, and
|
603
580
|
push the `.gem` files to [rubygems.org](https://rubygems.org).
|
604
581
|
|
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
582
|
## Disclaimer
|
612
583
|
|
613
584
|
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-spyke
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.19.0.rc1
|
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-06 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: fmrest-core
|
@@ -16,14 +16,14 @@ dependencies:
|
|
16
16
|
requirements:
|
17
17
|
- - '='
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version: 0.
|
19
|
+
version: 0.19.0.rc1
|
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.19.0.rc1
|
27
27
|
- !ruby/object:Gem::Dependency
|
28
28
|
name: spyke
|
29
29
|
requirement: !ruby/object:Gem::Requirement
|
@@ -88,9 +88,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
88
88
|
version: '0'
|
89
89
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
90
90
|
requirements:
|
91
|
-
- - "
|
91
|
+
- - ">"
|
92
92
|
- !ruby/object:Gem::Version
|
93
|
-
version:
|
93
|
+
version: 1.3.1
|
94
94
|
requirements: []
|
95
95
|
rubygems_version: 3.2.3
|
96
96
|
signing_key:
|