dummy-link

HTTPClient

HTTP client functionality (based on LibCURL.jl)

First Commit

07/06/2013

Last Touched

8 months ago

Commit Count

52 commits

Readme

HTTPClient.jl

Build Status Coverage Status

HTTPClient HTTPClient

Provides HTTP client functionality based on libcurl.

Usage

The exported APIs from module HTTPClient are :

get(url::String, options::RequestOptions)
get(url::String; kw_opts...)

post(url::String, data, options::RequestOptions)
post(url::String, data; kw_opts...)

put(url::String, data, options::RequestOptions)
put(url::String, data; kw_opts...)

data can be either a

  • String - sent as is.
  • IOStream - Content type is set to "application/octet-stream" unless specified otherwise
  • Dict{Name, Value} or Vector{Tuple{Name, Value}} - Content type is set to "application/x-www-form-urlencoded" unless specified otherwise
  • (:file, filename::String) - The file is read, and the content-type is set automatically unless specified otherwise. ``` head(url::String, options::RequestOptions) head(url::String; kw_opts...)

delete(url::String, options::RequestOptions) delete(url::String; kw_opts...)

trace(url::String, options::RequestOptions) trace(url::String; kw_opts...)

options(url::String, options::RequestOptions) options(url::String; kw_opts...)


Each API returns an object of type

type Response body::IOBuffer headers::Dict{String, Vector{String}} http_code::Int total_time::Float64 bytes_recd::Integer end


If you expecting ascii text as a response, for example, html content, or json,
`bytestring(r.body)` will return the stringified response. For binary data use the
functions described in http://docs.julialang.org/en/latest/stdlib/base/#i-o to access
the raw data.


### Specifying Options

Options can specified either as keyword arguments or a single object of type `RequestOptions`

type RequestOptions blocking::Bool query_params::Vector{Tuple} request_timeout::Float64 callback::Union(Function,Bool) content_type::String headers::Vector{Tuple} ostream::Union{IO, Nothing} auto_content_type::Bool end


`options` can also be specified as named arguments in each of the APIS. The names are field names of RequestOptions.
For example, ```get(url; blocking=false, request_timeout=30.0)```


- By default all APIs block till request completion and return Response objects.

- If ```blocking``` is set to ```false```, then the API returns immediately with a RemoteRef. The request is executed asynchronously in a separate task.

- The user can specify a complete url in the ```url``` parameter of the API, or can set query_params as a ```Vector``` of ```(Name, Value)``` tuples

  In the former case, the passed url is executed as is.

  In the latter case the complete URL if formed by concatenating the ```url``` field, a "?" and
  the escaped (name,value) pairs. Both the name and values must be convertible to appropriate ASCIIStrings.

- In file upload cases, an attempt is made to set the ```content_type``` type automatically as
  derived from the file extension unless ```auto_content_type``` is set to false.

- ```auto_content_type``` - default is true. If the content_type has not been explicitly specified,
  the library will try to guess the content type for a PUT/POST from the file extension.
  For POST it will default to "application/x-www-form-urlencoded". Set this parameter to false to override this behaviour

- Default value for the ```request_timeout``` is 0.0 seconds, i.e., never timeout.

- If a callback is specified, its signature should be  ```customize_cb(curl)``` where ```curl``` is the libCURL handle.
  The callback can further customize the request by using libCURL easy* APIs directly

- headers - additional headers to be set. Vector of {Name, Value} Tuples

- ostream - if set as an IO, any returned data to written to ostream.
  If it is a String, it is treated as a filename and written to the file.
  In both these cases the data is not returned as part of the Response object



# Samples

See `test/runtests.jl` for sample code


### TODO

Change the sleep in a loop to using fdwatcher when support for fdwatcher becomes available in mainline