saddle
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.
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
- Give these endpoints methods that call
Initialize an instance of your client. ex:
saddle_example_client = SaddleExample::Client.create
todo
- xml posting/parsing
version notes
- 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
Code Status
License
Saddle is released under the MIT License.