Transport
A HTTP/JSON transport layer. Provides a single command interface to perform http/json requests. A spec helper to perform request against a fake server is also included.
<img src=“http://travis-ci.org/phifty/transport.png” />
HTTP requests
To perform a http request the call of a single command is needed.
Transport::HTTP.request :get, "http://www.google.com", :expected_status_code => 200
The method will return a string with the content of Google home page. If another status code is received than the expected one, an Transport::UnexpectedStatusCodeError
will be raised. In that case, the status code can be read from the raised error object.
begin
Transport::HTTP.request :get, "http://www.google.com", :expected_status_code => 200
rescue Transport::UnexpectedStatusCodeError => error
puts "error code = #{error.status_code}"
end
Parameters, headers and the request body
Parameters and headers can also be passed to the request method.
Transport::HTTP.request :get, "http://www.somesite.com",
:parameters => { "test" => "test value" },
:headers => { "Accept" => "text/html", "Content-Type" => "application/x-www-form-urlencoded" }
Before performing a GET or DELETE request, the given parameters will be encoded in the request url (e.g. ?test=test%20value
). POST and PUT request will transport the encoded parameters in their request body, unless a request body is explicitly specified.
Transport::HTTP.request :post, "http://www.somesite.com",
:headers => { "Accept" => "text/html", "Content-Type" => "text/html" },
:body => "<html>some data</html>"
Authentication
Currently, BASIC authentication is supported for requests. To enable it, simply pass the parameter auth_type
along with username
and password
to the request method.
Transport::HTTP.request :get, "http://www.somesite.com",
:auth_type => :basic, :username => "user", :password => "pass"
JSON requests
A JSON request is basically an extensions of a HTTP request. All options that are possible on HTTP request are also possible on JSON requests. But a few differences should be mentioned here.
-
The
Accept
header will be set toapplication/json
anyway. -
If a request body is specified, the
Content-Type
will also be set toapplication/json
cause only json data should be transferred. -
If the option
encode_parameters
is set to true, all parameters will be encoded to json, before encoded to the url. This makes it possible to transfer more complex parameters like arrays and hashes. -
The response body will also be parsed to json.
Example
Transport::JSON.request :get, "http://www.somesite.com/content.json",
:auth_type => :basic, :username => "user", :password => "pass",
:parameters => { "filter" => { "date" => Date.today, "tags" => [ "gossip", "serious" ] } },
:encode_parameters => true
This will perform an authenticated GET request to the given url and passes the json-encoded parameters.
Fake requests
For test proposes, this gem also comes with the possibility of doing fake requests. If you want to test your code against a webservice, but don’t want to dependent on a network connection or on the webservice itself - or just want to speed up your tests, you can fake the webservice by calling Transport::Spec::Faker.fake!
.
describe "webservice" do
before :each do
Transport::Spec::Faker.fake! "some_filename.yml"
end
...
end
The given filename should point to a YML file that contains an array of all fake requests. The file should look like the following example.
-- # use a single dash here
:http_method: "get"
:url: "http://www.somesite.com/content.json"
:response:
:code: 200
:body:
"test": "test value"
-- # use a single dash here
:http_method: "post"
:url: "http://www.somesite.com"
:headers:
"Accept": "text/html"
"Content-Type": "text/html"
:response:
:code: 200
:body: "<html>test value</html>"
Once the faker is activated, it will try to fake any request. If your software is trying to do a request that isn’t defined in the YML file, it will raises a Transport::Spec::Faker::NoFakeRequestError
.
Development
This project is still under development. Any bug report and contribution is welcome!
Support
Apart from contribution, support via Flattr is welcome.