This package is DEPRECATED

We recommend that you use HTTP.jl instead. This package is no longer maintained and has reduced functionality and performance compared to HTTP.jl.

Requests.jl

An HTTP client written in Julia. Uses joyent/http-parser via HttpParser.jl.

Quickstart

julia> Pkg.add("Requests")

julia> using Requests
julia> import Requests: get, post, put, delete, options

Make a request

get("http://httpbin.org/get")
post("http://httpbin.org/post")
put("http://httpbin.org/put")
delete("http://httpbin.org/delete")
options("http://httpbin.org/get")

Add query parameters

get("http://httpbin.org/get"; query = Dict("title" => "page1"))
get("http://httpbin.org/get"; query = Dict("multi" => ["value1", "value2"]))

Add plain text data

post("http://httpbin.org/post"; data = "Hello World")

Add JSON data

post("http://httpbin.org/post"; json = Dict("id" => "1fc80620-7fd3-11e3-80a5"))

Add form-encoded data

post("http://httpbin.org/post"; data=Dict(email=>"a", pw=>"b"))

Request compressed data

get("http://httpbin.org/get"; compressed=true)

Send compressed data (GZip)

post("http://httpbin.org/post"; data="compress this data", gzip_data=true)

Set headers and cookies

post("http://httpbin.org/post"; headers = Dict("Date" => "Tue, 15 Nov 1994 08:12:31 GMT"),
                                cookies = Dict("sessionkey" => "abc"))

HTTP basic authentication is parsed and set as a proper Authorization header from the URI:

post("http://username:password@httpbin.org/post")

Set a timeout

This will throw an error if more than 500ms goes by without receiving any new bytes from the server.

get("http://httpbin.org/get"; timeout = .5)    # timeout = Dates.Millisecond(500) will also work

Controls redirects

By default, redirects will be followed. max_redirects and allow_redirects control this behavior.

get("http://httpbin.org/redirect/3"; max_redirects=2)  # Throws an error

# Returns a response redirecting the client to "www.google.com"
get("http://google.com"; allow_redirects=false)  

File upload

The three different ways to upload a file called test.jl (yes this uploads the same file three times).

    filename = "test.jl"
    post("http://httpbin.org/post"; files = [
      FileParam(readall(filename),"text/julia","file1","file1.jl"),
      FileParam(open(filename,"r"),"text/julia","file2","file2.jl",true),
      FileParam(IOBuffer(readall(filename)),"text/julia","file3","file3.jl"),
      ])
    ])

FileParam has the following constructors:

    immutable FileParam
        file::Union{IO,Base.File,AbstractString,Vector{UInt8}}     # The file
        # The content type (default: "", which is interpreted as text/plain serverside)
        ContentType::ASCIIString
        name::ASCIIString                                  # The fieldname (in a form)
        filename::ASCIIString                              # The filename (of the actual file)
        # Whether or not to close the file when the request is done
        close::Bool
    end

    FileParam(str::Union{AbstractString,Vector{UInt8}},ContentType="",name="",filename="")
    FileParam(io::IO,ContentType="",name="",filename="",close::Bool=false)

Inspect responses

Via accessors (preferred):

readstring(::Response)      # Get the payload of the response as a string
readbytes(::Response)       # Get the payload as a byte array
Requests.json(::Response)   # Parse a JSON-encoded response into a Julia object
statuscode(::Response)      # Get the HTTP status code
headers(::Response)         # A dictionary from response header fields to values
cookies(::Response)         # A dictionary from cookie names set by the server to Cookie objects
requestfor(::Response)      # Returns the request that generated the given response
Requests.history(::Response)# Returns the history of redirects that generated the given response.

or directly through the Response type fields:

type Response
    status::Int
    headers::Headers
    cookies::Cookies
    data::Vector{UInt8}
    request::Nullable{Request}
    history::Vector{Response}
end

Saving responses

cat = get("https://upload.wikimedia.org/wikipedia/commons/8/8e/Termografia_kot.jpg")
save(cat, "catpic.jpg")  # Save the payload to a file
view(cat)  # View the payload using your system's default applciation for its mimetype

Streaming API

Write bytes to disk as they are received:

stream = Requests.get_streaming("https://upload.wikimedia.org/wikipedia/commons/9/99/Black_cat_being_snowed_on.jpg")

open("cat.jpg", "w") do file
  while !eof(stream)
    write(file, readavailable(stream))
  end
end

Stream out data of potentially unknown length using chunked encoding:

stream = Requests.post_streaming("http://htpbin.org/post",
  headers=Dict("Transfer-Encoding"=>"chunked"), write_body=false)  
# `write_body=false` causes `post_streaming` to only write the headers, allowing you the chance to write the body manually
for data_chunk in ["first", "second"]
    write_chunked(stream, data_chunk)
end
write_chunked(stream, "")  # Signal that the body is complete

response = readall(stream)  # Get back the server's response