dummy-link

HTTPClient

HTTP client functionality (based on LibCURL.jl)

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





First Commit

07/06/2013

Last Touched

about 1 year ago

Commits

52 commits