A Faraday Cage for your HTTP Interactions.
One of my favorite utilities for testing my APIs is Rack::Test. However, it gets really offended if you try to use it in an interactive session. I ended up using Faraday and hacked together a set of scripts that made interacting with my APIs easy and fun. I've re-written, cleaned up, and expanded upon these scripts and the result is Cage, a Pry-based console which implements a Rack::Test-like internal Ruby DSL. If you don't like the name, I'm open to suggestions. :D
Short Answer: Anything Faraday can do, Cage can do. However, I am attempting to make it natural and easy to use in an interactive manner.
By default, the four HTTP verbs, get, post, put, and delete, are
available and if you prefer you can use them in SHOUTCASE in order to feel
special about it. Each of these will return a Cage::Response, which is a thin
wrapper around a Faraday::Response that facilitates prettier printing and at the
moment, the type detection and auto-parsing of JSON and XML.
Cage will also keep track of where you're at so you don't have to keep entering the fully-qualified domain name or any prefixes common to all your requests.
For example, if you want to hit version one of the Rubygems.org API just set the domain and prefix.
└─> bundle exec cage
[rubygems.org:]-> set :scheme, :http
=> :http
[rubygems.org:]-> set :domain, "rubygems.org"
=> "rubygems.org"
[rubygems.org:]-> set :prefix, "api/v1/gems"
=> "api/v1/gems"
[rubygems.org:]-> get "rails.json"
=>
Status: 200
Headers:
date: Sat, 28 Jan 2012 06:57:49 GMT
server: Apache/2.2.3 (Red Hat) mod_ssl/2.2.3 OpenSSL/0.9.8e-fips-rhel5 Phusion_Passenger/3.0.11
x-powered-by: Phusion Passenger (mod_rails/mod_rack) 3.0.11
etag: "6bc2525a176ae07870d12b35d6c78dcf"
cache-control: max-age=0, private, must-revalidate
x-ua-compatible: IE=Edge,chrome=1
x-runtime: 0.025598
status: 200
content-length: 1096
connection: close
content-type: application/json; charset=utf-8
Body:
{"name"=>"rails", "downloads"=>7422057, "version"=>"3.2.1", .... }
#<Cage::Response:(http://rubygems.org/api/v1/gems/rails.json)>
[rubygems.org:200]-> get "rails.xml"
=>
Status: 200
Headers:
date: Sat, 28 Jan 2012 06:57:53 GMT
server: Apache/2.2.3 (Red Hat) mod_ssl/2.2.3 OpenSSL/0.9.8e-fips-rhel5 Phusion_Passenger/3.0.11
x-powered-by: Phusion Passenger (mod_rails/mod_rack) 3.0.11
etag: "fd13fd2f31fa180391b2e9a9b3c08b79"
cache-control: max-age=0, private, must-revalidate
x-ua-compatible: IE=Edge,chrome=1
x-runtime: 0.034550
status: 200
content-length: 1915
connection: close
content-type: application/xml; charset=utf-8
Body:
{"rubygem"=>{"name"=>"rails", "downloads"=>7422057, "version"=>"3.2.1", ... }
#<Cage::Response:(http://rubygems.org/api/v1/gems/rails.xml)>
[rubygems.org:200]-> get "wontbethere"
=>
Status: 404
Headers:
date: Sat, 28 Jan 2012 07:43:53 GMT
server: Apache/2.2.3 (Red Hat) mod_ssl/2.2.3 OpenSSL/0.9.8e-fips-rhel5 Phus
x-powered-by: Phusion Passenger (mod_rails/mod_rack) 3.0.11
cache-control: no-cache
x-ua-compatible: IE=Edge,chrome=1
x-runtime: 0.011617
status: 404
vary: Accept-Encoding
content-length: 1053
connection: close
content-type: text/html; charset=utf-8
Body:
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
Currently, Cage is attempting to remain feature reduced and free of opinions. I have attempted to include of all elements of the Rack::Test DSL that I wish I'd had when hand-testing my APIs or investigating new ones. If there's something you wish Cage did that is not currently available. Please do File an issue and I will do my best to accomodate your request.
Once Cage hits 0.1.0, it will be released as a gem. Then you can install it
globally with gem install cage. Better still, add it to the Gemfile of your
project.
group :development do
gem "cage"
endRunning cage will begin a console session. Cage is like a specialized IRB, but
for HTTP interactions. Imagine that you are working on an API. [Rack::Test][rt]
is an awesome tool but when you try to use it interactively you get an
interesting display of fireworks(read: stacktraces). Cage is based on a utility
script I wrote while working on a REST API. Some days, you just want to monkey
around with your work.
When you run Cage, you're dropped into a special Pry terminal with HTTP related commands available.
-
HTTP Methods:
GET/get: url, params, headersHEAD/head: url, params, headersDELETE/delete: url, params, headersPOST/post: url, body, headersPUT/put: url, body, headersPATCH/patch: url, body, headers
-
Cage Methods for Requests
basic_auth: login, passtoken_auth: token, optionsadd_middleware: middleware_builder_block
-
Anything else Ruby can do...
NOTE Global Configs aren't supported yet. Local configs and specified configs are working.
Cage will look first for a global ~/.cagerc.rb file, then for a localr
./cagerc.rb in the working directory. Both are essentially instance_eval'd
into your new Cage console so anything that works in Cage will work in a config.
The global one is run first, so you can overload it with a local config. The
local config is for setting up project defaults, you can even automate your
initial authentication if you want.
-
0.2.0 Write tests for whatever I can. WIP Study Pry's tests and read up on testing apps like this in Build Awesome Command-Line Applications in Ruby
-
0.3.0 Make it easier to send XML, YAML, and JSON formatted bodies.
-
0.4.0 Make some decisions about Auth.