README.md in fmrest-spyke-0.18.0 vs README.md in fmrest-spyke-0.19.0.rc1
- old
+ new
@@ -3,48 +3,59 @@
[](https://rubygems.org/gems/fmrest)
[](https://rubydoc.info/github/beezwax/fmrest-ruby)
A Ruby client for
-[FileMaker 18 and 19's Data API](https://help.claris.com/en/data-api-guide)
-using
-[Faraday](https://github.com/lostisland/faraday) and with optional
-ActiveRecord-ish ORM features through [Spyke](https://github.com/balvig/spyke).
+[FileMaker's Data API](https://help.claris.com/en/data-api-guide)
+with ActiveRecord-ish ORM features.
-fmrest-ruby only partially implements FileMaker 19's Data API.
-See the [implementation completeness table](#api-implementation-completeness-table)
-to see if a feature you need is natively supported by the gem.
+While pretty feature-rich, fmrest-ruby doesn't yet support 100% of FileMaker
+19's Data API features. See the [implementation completeness
+table](#api-implementation-completeness-table) to check if a feature you need
+is natively supported by the gem.
+## Contents
+
+* [Gems](#gems)
+* [Installation](#installation)
+* [Simple example](#simple-example)
+* [Connection settings](#connection-settings)
+* [Session token store](#session-token-store)
+* [Date fields and timezones](#date-fields-and-timezones)
+* [ActiveRecord-like ORM (fmrest-spyke)](#activerecord-like-orm--fmrest-spyke-)
+* [Logging](#logging)
+* [Gotchas](#gotchas)
+* [API implementation completeness table](#api-implementation-completeness-table)
+* [Supported Ruby versions](#supported-ruby-versions)
+
## Gems
The `fmrest` gem is a wrapper for two other gems:
* `fmrest-spyke`, providing an ActiveRecord-like ORM library built on top
of `fmrest-core` and [Spyke](https://github.com/balvig/spyke).
-* `fmrest-core`, providing the core Faraday connection builder, session
+* `fmrest-core`, providing the core
+ [Faraday](https://github.com/lostisland/faraday) connection builder, session
management, and other core utilities.
+In addition, the optional `fmrest-cloud` gem adds support for FileMaker Cloud.
+See the [main document on connecting to FileMaker
+Cloud](docs/FileMakerCloud.md).
+
## Installation
-Add this to your Gemfile:
+In your Gemfile:
```ruby
gem 'fmrest'
-```
-Or if you just want to use the Faraday connection without the ORM features:
-
-```ruby
-gem 'fmrest-core'
+# Optional: if your files are hosted on FileMaker Cloud
+gem 'fmrest-cloud'
```
-## Simple examples
+## Simple example
-### ORM example
-
-Most people would want to use the ORM features:
-
```ruby
# A Layout model connecting to the "Honeybees Web" FileMaker layout
class Honeybee < FmRest::Layout("Honeybees Web")
# Connection settings
self.fmrest_config = {
@@ -88,49 +99,22 @@
bee.tasks.build(urgency: "Today")
bee.save
```
-### Barebones connection example (without ORM)
-
-In case you don't need the advanced ORM features (e.g. if you only need minimal
-Data API interaction and just want a lightweight solution) you can simply use
-the Faraday connection provided by `fmrest-core`:
-
-```ruby
-connection = FmRest::V1.build_connection(
- host: "…",
- database: "…",
- username: "…",
- password: "…"
-)
-
-# Get all records (as parsed JSON)
-connection.get("layouts/FancyLayout/records")
-
-# Create new record
-connection.post do |req|
- req.url "layouts/FancyLayout/records"
-
- # You can just pass a hash for the JSON body
- req.body = { … }
-end
-```
-
+In case you don't want the ORM features (i.e. you only need authentication and
+JSON parsing, and are comfortable writing the API requests manually without the
+ORM overhead) you can use the Faraday connection provided by `fmrest-core`.
See the [main document on using the base
connection](docs/BaseConnectionUsage.md) for more.
## Connection settings
The minimum required connection settings are `:host`, `:database`, `:username`
and `:password`, but fmrest-ruby has many other options you can pass when
setting up a connection (see [full list](#full-list-of-available-options) below).
-If you're using FileMaker Cloud you may need to pass `:fmid_token` instead
-of the regular `:username` and `:password`. See the [main document on
-connecting to FileMaker Cloud](docs/FileMakerCloud.md) for more info.
-
`:ssl` and `:proxy` are forwarded to the underlying
[Faraday](https://github.com/lostisland/faraday) connection. You can use this
to, for instance, disable SSL verification:
```ruby
@@ -151,11 +135,10 @@
`:host` | Hostname with optional port, e.g. `"example.com:9000"` | String | None
`:database` | The name of the database to connect to | String | None
`:username` | A Data API-ready account | String | None
`:password` | Your password | String | None
`:account_name` | Alias of `:username` | String | None
-`:fmid_token` | Claris ID token (only needed for FileMaker Cloud) | String | None
`:ssl` | SSL options to be forwarded to Faraday | Faraday SSL options | None
`:proxy` | Proxy options to be forwarded to Faraday | Faraday proxy options | None
`:log` | Log JSON responses to STDOUT | Boolean | `false`
`:log_level` | Which log level to log into | Values accepted by `Logger#level=` | `:debug`
`:coerce_dates` | See section on [date fields](#date-fields-and-timezones) | Boolean \| `:hybrid` \| `:full` | `false`
@@ -163,10 +146,15 @@
`:timestamp_format` | Timestmap parsing format | String (FM date format) | `"MM/dd/yyyy HH:mm:ss"`
`:time_format` | Time parsing format | String (FM date format) | `"HH:mm:ss"`
`:timezone` | The timezone for the FM server | `:local` \| `:utc` \| `nil` | `nil`
`:autologin` | Whether to automatically start Data API sessions | Boolean | `true`
`:token` | Used to manually provide a session token (e.g. if `:autologin` is `false`) | String | None
+`:fmid_token` | Claris ID token (only needed if manually obtaining the token) | String | None
+`:cloud` | Specifies whether the host is using FileMaker Cloud | `:auto` \| Boolean | `:auto`
+`:cognito_client_id`| Overwrites the hardcoded FileMaker Cloud Cognito Client ID | String | None
+`:cognito_pool_id` | Overwrites the hardcoded FileMaker Cloud Cognito Pool ID | String | None
+`:aws_region` | Overwrites the hardcoded FileMaker Cloud AWS Region | String | None
### Default connection settings
If you're only connecting to a single FM database you can configure it globally
through `FmRest.default_connection_settings=`. E.g.:
@@ -205,11 +193,11 @@
See the [main document on date fields](docs/DateFields.md) for more info.
## ActiveRecord-like ORM (fmrest-spyke)
[Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for
-building REST ORM models. fmrest-ruby builds its ORM features atop Spyke,
+building REST ORM models. fmrest-ruby uses it to build its ORM features,
bundled in the `fmrest-spyke` gem (already included if you're using the
`fmrest` gem).
To create a model you can inherit directly from `FmRest::Layout` (itself a
subclass of `Spyke::Base`).
@@ -263,43 +251,37 @@
password: "…"
}
end
```
-This will automatically create a proper Faraday connection using those
-connection settings, so you don't have to worry about setting that up.
-
-Note that these settings are inheritable, so you could create a base class that
+These settings are class-inheritable, so you could create a base class that
does the initial connection setup and then inherit from it in models using that
same connection. E.g.:
```ruby
-class BeeBase < FmRest::Layout
+class ApplicationFmLayout < FmRest::Layout
self.fmrest_config = { host: "…", database: "…", … }
end
-class Honeybee < BeeBase
- # This model will use the same connection as BeeBase
+class Honeybee < ApplicationFmLayout
+ # This model will use the same connection as ApplicationFmLayout
end
```
-Also, if not set, your model will try to use
+If `fmrest_config` is not set, your model will try to use
`FmRest.default_connection_settings` instead.
#### Connection settings overlays
There may be cases where you want to use a different set of connection settings
-depending on context, or simply change the connection settings over time. For
-example, if you want to use username and password provided by the user in a web
-application, or if you're connecting using an expiring Claris ID token. Since
-`.fmrest_config` is set at the class level, changing the username/password for
-the model in one context would also change it in all other contexts, leading to
-security issues.
+depending on context. For example, if you want to use username and password
+provided by the user in a web application. Since `.fmrest_config` is set at the
+class level, changing the username/password for the model in one context would
+also change it in all other contexts, leading to security issues.
-To solve this scenario, fmrest-ruby provides a way of defining thread-local and
-reversible connection settings overlays through
-`.fmrest_config_overlay=`.
+To solve this scenario, fmrest-ruby provides a way of defining thread-local,
+reversible connection settings overlays through `.fmrest_config_overlay=`.
See the [main document on connection setting overlays](docs/ConfigOverlays.md)
for details on how it works.
### FmRest::Layout.layout
@@ -459,26 +441,21 @@
See the [main document on setting global field values](docs/GlobalFields.md)
for details.
### Rescuable mixin
-Sometimes you may want to handle Data API errors at the model level. For
-instance, if you're logging in to a file hosted by FileMaker Cloud using a
-Claris ID token, and you want to be able to renew said token when it fails to
-log you in. For such cases fmrest-ruby provides an off-by-default mixin called
-`Rescuable` that provides convenience macros for that. If you've used Ruby on
-Rails you may be familiar with its syntax from controllers. E.g.
+Sometimes you may want to handle Data API errors at the model level. For such
+cases fmrest-ruby provides an off-by-default mixin called `Rescuable` that
+provides convenience macros for that. If you've used Ruby on Rails you may be
+familiar with its syntax from controllers. E.g.
```ruby
class BeeBase < FmRest::Layout
include FmRest::Spyke::Model::Rescuable
rescue_from FmRest::APIError::SystemError, with: :notify_admin_of_system_error
- # Shorthand for rescue_with FmRest::APIError::AccountError, ...
- rescue_account_error { ClarisIDTokenManager.expire_token }
-
def self.notify_admin_of_system_error(e)
# Shoot an email to the FM admin...
end
end
```
@@ -547,18 +524,18 @@
Read about unexpected scenarios in the [gotchas doc](docs/Gotchas.md).
## API implementation completeness table
-FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/
+FM Data API reference: https://help.claris.com/en/data-api-guide/
-| FM 18 Data API feature | Supported by basic connection | Supported by FmRest::Layout |
+| FM 19 Data API feature | Supported by basic connection | Supported by FmRest::Layout |
|-------------------------------------|-------------------------------|-----------------------------|
| Log in using HTTP Basic Auth | Yes | Yes |
| Log in using OAuth | No | No |
| Log in to an external data source | No | No |
-| Log in using Claris ID account | Yes | Yes |
+| Log in using Claris ID account (FileMaker Cloud) | Yes | Yes |
| Log out | Yes | Yes |
| Get product information | Manual* | No |
| Get database names | Manual* | No |
| Get script names | Manual* | No |
| Get layout names | Manual* | No |
@@ -590,24 +567,18 @@
* Ruby 3.0
## Gem development
After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake spec` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment (it will auto-load all fixtures in
-spec/fixtures).
+`bundle exec rspec` to run the specs. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment (it will auto-load all
+fixtures in spec/fixtures).
To install all gems onto your local machine, run
`bundle exec rake all:install`. To release a new version, update the version
number in `lib/fmrest/version.rb`, and then run `bundle exec rake all:release`,
which will create a git tag for the version, push git commits and tags, and
push the `.gem` files to [rubygems.org](https://rubygems.org).
-
-## License
-
-The gem is available as open source under the terms of the
-[MIT License](https://opensource.org/licenses/MIT).
-See [LICENSE.txt](LICENSE.txt).
## Disclaimer
This project is not sponsored by or otherwise affiliated with Claris
International Inc., an Apple Inc. subsidiary. FileMaker is a trademark of