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
client construction
-
For the sake of cleanliness, pick a namespace that everything related to your client should live in. For this example, we'll use SaddleExample.
-
Inherit your client class, SaddleExample::Client, from Saddle::Client.
-
Create an endpoints directory at the same level as your client class file.
-
Create endpoint classes in the endpoints directory that inherit from Saddle::TraversalEndpoint and are under the SaddleExample::Endpoints namespace module.
-
Give these endpoints methods that call
get
orpost
to perform the actual request -
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
-
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
-
-
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.