README.md in fmrest-0.10.1 vs README.md in fmrest-0.11.0
- old
+ new
@@ -1,8 +1,9 @@
# fmrest-ruby
-<a href="https://rubygems.org/gems/fmrest"><img src="https://badge.fury.io/rb/fmrest.svg?style=flat" alt="Gem Version"></a>
+[](https://rubygems.org/gems/fmrest)
+
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
@@ -119,10 +120,12 @@
`:coerce_dates` | See section on [date fields](#date-fields) | Boolean \| `:hybrid` \| `:full` | `false`
`:date_format` | Date parsing format | String (FM date format) | `"MM/dd/yyyy"`
`: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
### 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.:
@@ -416,10 +419,63 @@
class Honeybee < BeeBase
# This model will use the same connection as BeeBase
end
```
+### Model.fmrest_config_overlay=
+
+There may be cases where you want to use different connection settings
+depending on context, for example if you want to use username and password
+provided by the user in a web application. Since `Model.fmrest_config` is
+global, changing the username/password for one context would also change it for
+all other contexts, leading to security issues.
+
+`Model.fmrest_config_overlay=` solves that issue by allowing you to override
+some settings in a thread-local and reversible manner. That way, using the same
+example as above, you could connect to the Data API with user-provided
+credentials without having them leak into other users of your web application.
+
+E.g.:
+
+```ruby
+class BeeBase < Spyke::Base
+ include FmRest::Spyke
+
+ # Host and database provided as base settings
+ self.fmrest_config = {
+ host: "example.com",
+ database: "My Database"
+ }
+end
+
+# E.g. in a controller-action of a Rails application:
+
+# User-provided credentials
+BeeBase.fmrest_config_overlay = {
+ username: params[:username],
+ password: params[:password]
+}
+
+# Perform some Data API requests ...
+```
+
+### Model.clear_fmrest_config_overlay
+
+Clears the thread-local settings provided to `fmrest_config_overaly=`.
+
+### Model.with_overlay
+
+Runs a block with the given settings overlay, resetting them after the block
+finishes running. It wraps execution in its own fiber, so it doesn't affect the
+overlay of the currently-running thread.
+
+```ruby
+Honeybee.with_overlay(username: "...", password: "...") do
+ Honeybee.query(...)
+end
+```
+
### Model.layout
Use `layout` to set the `:layout` part of API URLs, e.g.:
```ruby
@@ -431,9 +487,18 @@
This is much preferred over using Spyke's `uri` to set custom URLs for your
Data API models.
Note that you only need to set this if the name of the model and the name of
the layout differ, otherwise the default will just work.
+
+### Model.request_auth_token
+
+Requests a Data API session token using the connection settings in
+`fmrest_config` and returns it if successful, otherwise returns `false`.
+
+You normally don't need to use this method as fmrest-ruby will automatically
+request and store session tokens for you (provided that `:autologin` is
+`true`).
### Model.logout
Use `logout` to log out from the database session (you may call it on any model
that uses the database session you want to log out from).