Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A Ruby framework for service clients
branch: master


Giddyup nerd! Wrangle your SOA.

Saddle makes writing service clients as easy as giving high fives. :hand:

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


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.



  • 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


  • 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


concrete example


client construction

  1. For the sake of cleanliness, pick a namespace that everything related to your client should live in. For this example, we'll use SaddleExample
  2. Inherit your client class, SaddleExample::Client, from Saddle::Client
  3. Create an endpoints directory at the same level as your client class file
  4. 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:

    3. If you need REST style endpoints like'guppy').catch() then check out Saddle::ResourceEndpoint and how it's used in saddle-example

  5. Initialize an instance of your client. ex:

    saddle_example_client = SaddleExample::Client.create


  • xml posting/parsing

Code Status

  • Build Status
  • Code Climate
  • Dependency Status


Saddle is released under the MIT License.

Something went wrong with that request. Please try again.