mlewislogic / saddle

A Ruby framework for service clients

saddle

Giddyup nerd! Wrangle your SOA.

Saddle makes writing service clients as easy as giving high fives. ✋

It's a full-featured, generic consumer layer for you to build API client implementations with.

about

Ok, I love high fives, but what does Saddle do for me?

Saddle is a framework that makes it exceptionally easy to write HTTP API clients. It abstracts away a lot of the repetitive work and lets you focus on your business logic. It also provides a simple middleware interface that makes it easy to extend functionality.

Saddle enables you to create beautifully stable and functionaly API clients, in the fewest lines of code possible.

features

client

• Specifying default connection settings for your client makes usage simple
• Automatic call tree construction, based upon module/class namespace
• Easily integrate with logging systems (currently supports statsd & Airbrake)
• Support simple testing of your client

requests

• Post urlencoded or JSON (handles multipart file posts as well)
• Auto-parse JSON responses
• Strictly enforce request timeouts (client-wide or endpoint specific timeouts)

error handling

• Automatic retries with exponential backoff
• Turns 4xx and 5xx responses into exceptions
• If desired, silently return default values upon exception

guide

concrete example

saddle-example

client construction

0. For the sake of cleanliness, pick a namespace that everything related to your client should live in. For this example, we'll use SaddleExample.

1. Inherit your client class, SaddleExample::Client, from Saddle::Client.

2. Create an endpoints directory at the same level as your client class file.

3. Create endpoint classes in the endpoints directory that inherit from Saddle::TraversalEndpoint and are under the SaddleExample::Endpoints namespace module.

   1. Give these endpoints methods that call get or post to perform the actual request

   2. Their module/class namespace determines how they are accessed in the client's call tree. For example, the get_all in SaddleExample::Endpoints::Fish::Guppy would be accessed by:

       client.fish.guppy.get_all
      

   3. If you need REST style endpoints like client.kitten.by_id('Whiskers').info then check out Saddle::ResourceEndpoint and how it's used in saddle-example

4. Initialize an instance of your client. ex:

    saddle_example_client = SaddleExample::Client.create
   

todo

• xml posting/parsing

version notes

• Saddle versions 0.2.x supports Ruby 3.x, drops support for 2.6
• Saddle versions 0.1.x are compatible with Faraday versions ~> 0.9.0
• Saddle versions 0.0.x are compatible with Faraday versions ~> 0.8.7

Appraisal Usage

Appraisal is a gem that allows us to test our library against different versions of dependencies in repeatable scenarios called "appraisals". For more information see the Appraisal repository

First make sure appraisal is installed by running

$ bundle install

To update the Appraisal's gemfiles run

$ bundle exec appraisal generate

To test against a specific version of activesupport first install the dependencies, ideally we would want to install them by running

$ bundle exec appraisal install

However, this isn't posible fot the different constraints these versions have. So instead install the dependencies for the desired version we want to test against by running

$ BUNDLE_GEMFILE=gemfiles/activesupport_6.0.gemfiles bundle install

In this example we want to install the dependencies of activesupport version 6.0. Then to run rspec with that constraints we run

$ BUNDLE_GEMFILE=gemfiles/activesupport_6.0.gemfiles bundle exec rspec

Code Status

• 

License

Saddle is released under the MIT License.