The `fulfil_api` Ruby gem

The fulfil_api is a simple, powerful HTTP client written in Ruby to interact with Fulfil's API. It takes learnings from many years of working with Fulfil's APIs and turns it into an easy to use HTTP client.

Installation

Install the gem and add to the application's Gemfile by executing:

  $ bundle add fulfil_api

If bundler is not being used to manage dependencies, install the gem by executing:

  $ gem install fulfil_api

Usage

Configuration

There are two ways of configuring the HTTP client:

Staticly through an initializer file (typically used in a Rails application)
Dynamically through calling the FulfilApi.with_config method.

The configuration of the FulfilApi client is thread-safe and therefore you can even combine both the static and dynamic configuration of Fulfil in case you need to.

Using a Static Configuration

# config/initializers/fulfil_api.rb

FulfilApi.configure do |config|
  config.access_token = FulfilApi::AccessToken.new(ENV["FULFIL_API_KEY"])
  config.merchant_id = "the-id-of-the-merchant"
end

Using a Dynamic Configuration

FulfilApi.with_config(
  access_token: FulfilApi::AccessToken.new(ENV["FULFIL_API_KEY"]),
  merchant_id: "the-id-of-the-merchant"
) do
  # Query the Fulfil API
end

Available Configuration Options

The following configuration options are (currently) available throught both configuration methods:

access_token (FulfilApi::AccessToken): The access_token is required to authenticate with Fulfil's API endpoints. Fulfil supports two types of access tokens: "OAuth" and "Personal" access tokens. The gem supports both tokens and defaults to the personal access token.

NOTE: To use an OAuth access token, use FulfilApi::AccessToken.new(oauth_token, type: :oauth). Typically, you would use the OAuth access token only when using the dynamic configuration mode of the gem.

merchant_id (String): The merchant_id is the subdomain that the Fulfil instance is hosted on. This configuration option is required to be able to query Fulfil's API endpoints.

Querying the Fulfil API

NOTE: Currently, the gem is under heavy development. The querying interface of the gem is really basic at the moment. In the future, we will closer match the querying interface of ActiveRecord.

The gem uses an ActiveRecord like query interface to query the Fulfil API.

# Find one specific resource
sales_order = FulfilApi::Resource.set(name: "sale.sale").find_by(["id", "=", 100])
p sales_order["id"] # => 100

# Find a list of resources
sales_orders = FulfilApi::Resource.set(name: "sale.sale").where(["channel", "=", 4])
p sales_orders.size # => 500 (standard number of resources returned by Fulfil)
p sales_orders.first["id"] # => 10 (an example of an ID returned by Fulfil)

# Find a limited list of resources
sales_orders = FulfilApi::Resource.set(name: "sale.sale").where(["channel", "=", 4]).limit(50)
p sales_orders.size # => 50

# Include more resource details than the ID only
sales_orders = FulfilApi::Resource.set(name: "sale.sale").select("reference").where(["channel", "=", 4])
p sales_orders.first["reference"] # => SO1234

# Fetch nested data from a relation
line_items = FulfilApi::Resource.set(name: "sale.line").select("sale.reference")
p line_items.first["sale"]["reference"] # => SO1234

# Query nested data from a relation
line_items = FulfilApi::Resource.set(name: "sale.line").where(["sale.reference", "=", "SO1234"])
p line_items.first["id"] # => 10

NOTE: It's important to note that the results from the Fulfil API are cached. This prevents you from accidentally overasking the Fulfil API. To reload the resources from the Fulfil API after you've already fetchted them, use the .reload on the returned relation (e.g. line_items.reload).

Interacting with the `FulfilApi::Resource`

Any data returned through the FulfilApi gem returns a list or a single FulfilApi::Resource. The data of the API resource is accessible through a Hash-like method.

sales_order = FulfilApi::Resource.set(name: "sale.sale").find_by(["id", "=", 100])
p sales_order["id"] # => 100

When you're requesting relational data for an API resource, you can access it in a similar manner.

sales_order = FulfilApi::Resource.set(name: "sale.sale").select("channel.name").find_by(["id", "=", 100])
p sales_order["channel"]["name"] # => Shopify

NOTE: Fulfil is not able to return nested data from Array-like API resources. If you want to find all line items of a sales order, it's typically better to query the line item resource directly.

# You can't do this
FulfilApi::Resource.set(name: "sale.sale").select("lines.reference").find_by(["id", "=", 100])

# You can do this (BUT it's not recommended)
sales_order = FulfilApi::Resource.set(name: "sale.sale").select("lines").find_by(["id", "=", 100])
line_items = FulfilApi::Resource.set(name: "sale.line").where(["id", "in", sales_order["lines"]])

# You can do this (recommended)
line_items = FulfilApi::Resource.set(name: "sale.line").find_by(["sale.id", "=", 100])

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bin/rake install.

Releasing

To release a new version, run the bin/release script. This will update the version number in version.rb, create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/codeturebv/fulfil_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Fulfil project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

The fulfil_api Ruby gem