Iter - a Ruby client for the Iterable API

Iter helps you write apps that need to interact with Iterable.

The source code is available on GitHub and the documentation on RubyDoc.

After registering your app, you can run commands like:

Iter::User.new(id:).update email:, fields:
Iter::User.new(id:).delete
Iter::Event.create(user_id:, name:, fields:)

The full documentation is available at rubydoc.info.

How to install

To install on your system, run

gem install iter

To use inside a bundled Ruby project, add this line to the Gemfile:

gem 'iter', '~> 1.0'

Since the gem follows Semantic Versioning, indicating the full version in your Gemfile (~> major.minor.patch) guarantees that your project won’t occur in any error when you bundle update and a new version of Iter is released.

Configuring your app

In order to use Iter you must have credentials to the Iterable API.

Add them to your code with the following snippet of code (replacing with your own credentials):

Iter.configure do |config|
  config.api_key = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'
end

Mocking the Iterable API

Sometimes you want to mock the API requests to Iterable and obtain results that are equivalent to the original API calls. This can be useful to test your flow without hitting the API.

Configuring with environment variables

As an alternative to the approach above, you can configure your app with variables. Setting the following environment variables:

export ITER_API_KEY="ABCDEFGHIJKLMNOPQRSTUVWXYZ012345"

is equivalent to the previous approach so pick the one you prefer. If a variable is set in both places, then Iter.configure takes precedence.

How to test

To run tests:

rspec

By default, tests are run with real HTTP calls to Iterable that must be set with the environment variables specified above.

If you do not have access to Iterable, you can still run the tests mocked:

ITER_MOCK=1 rspec

How to release new versions

If you are a manager of this project, remember to upgrade the Iter gem whenever a new feature is added or a bug gets fixed. Make sure all the tests are passing and the code is 100% test-covered. Document the changes in CHANGELOG.md and README.md, bump the version, then run:

rake release

Remember that the iter gem follows Semantic Versioning. Any new release that is fully backward-compatible should bump the minor version (1.x). Any new version that breaks compatibility should bump the major version (x.0)

How to contribute

Iter needs your support! The goal of Iter is to provide a Ruby interface for all the methods exposed by the Iterable API.

If you find that a method is missing, fork the project, add the missing code, write the appropriate tests, then submit a pull request, and it will gladly be merged!