API Reference

API Reference

Client Requests

HTTP.request — Function

HTTP.request(method, url [, headers [, body]]; <keyword arguments>]) -> HTTP.Response

Send a HTTP Request Message and receive a HTTP Response Message.

e.g.

r = HTTP.request("GET", "http://httpbin.org/ip")
r = HTTP.get("http://httpbin.org/ip") # equivalent shortcut
println(r.status)
println(String(r.body))

headers can be any collection where [string(k) => string(v) for (k,v) in headers] yields Vector{Pair}. e.g. a Dict(), a Vector{Tuple}, a Vector{Pair} or an iterator. By convention, if a header value is an empty string, it will not be written when sending a request (following the curl convention). By default, a copy of provided headers is made (since required headers are typically set during the request); to avoid this copy and have HTTP.jl mutate the provided headers array, pass copyheaders=false as an additional keyword argument to the request.

The body argument can be a variety of objects:

an AbstractDict or NamedTuple to be serialized as the "application/x-www-form-urlencoded" content type
any AbstractString or AbstractVector{UInt8} which will be sent "as is" for the request body
a readable IO stream or any IO-like type T for which eof(T) and readavailable(T) are defined. This stream will be read and sent until eof is true. This object should support the mark/reset methods if request retries are desired (if not, no retries will be attempted).
Any collection or iterable of the above (AbstractDict, AbstractString, AbstractVector{UInt8}, or IO) which will result in a "chunked" request body, where each iterated element will be sent as a separate chunk
a HTTP.Form, which will be serialized as the "multipart/form-data" content-type

The HTTP.Response struct contains:

status::Int16 e.g. 200
headers::Vector{Pair{String,String}} e.g. ["Server" => "Apache", "Content-Type" => "text/html"]
body::Vector{UInt8} or ::IO, the Response Body bytes or the io argument provided via the response_stream keyword argument

Functions HTTP.get, HTTP.put, HTTP.post and HTTP.head are defined as shorthand for HTTP.request("GET", ...), etc.

Supported optional keyword arguments:

query = nothing, a Pair or Dict of key => values to be included in the url
response_stream = nothing, a writeable IO stream or any IO-like type T for which write(T, AbstractVector{UInt8}) is defined. The response body will be written to this stream instead of returned as a Vector{UInt8}.
verbose = 0, set to 1 or 2 for increasingly verbose logging of the request and response process
connect_timeout = 30, close the connection after this many seconds if it is still attempting to connect. Use connect_timeout = 0 to disable.
pool = nothing, an HTTP.Pool object to use for managing the reuse of connections between requests. By default, a global pool is used, which is shared across all requests. To create a pool for a specific set of requests, use pool = HTTP.Pool(max::Int), where max controls the maximum number of concurrent connections allowed to be used for requests at a given time.
readtimeout = 0, abort a request after this many seconds. Will trigger retries if applicable. Use readtimeout = 0 to disable.
status_exception = true, throw HTTP.StatusError for response status >= 300.
Basic authentication is detected automatically from the provided url's userinfo (in the form scheme://user:password@host) and adds the Authorization: Basic header; this can be disabled by passing basicauth=false
canonicalize_headers = false, rewrite request and response headers in Canonical-Camel-Dash-Format.
proxy = proxyurl, pass request through a proxy given as a url; alternatively, the http_proxy, HTTP_PROXY, https_proxy, HTTPS_PROXY, and no_proxy environment variables are also detected/used; if set, they will be used automatically when making requests.
detect_content_type = false: if true and the request body is not a form or IO, it will be inspected and the "Content-Type" header will be set to the detected content type.
decompress = nothing, by default, decompress the response body if the response has a "Content-Encoding" header set to "gzip". If decompress=true, decompress the response body regardless of Content-Encoding header. If decompress=false, do not decompress the response body.
logerrors = false, if true, HTTP.StatusError, HTTP.TimeoutError, HTTP.IOError, and HTTP.ConnectError will be logged via @error as they happen, regardless of whether the request is then retried or not. Useful for debugging or monitoring requests where there's worry of certain errors happening but ignored because of retries.
logtag = nothing, if provided, will be used as the tag for error logging. Useful for debugging or monitoring requests.
observelayers = false, if true, enables the HTTP.observelayer to wrap each client-side "layer" to track the amount of time spent in each layer as a request is processed. This can be useful for debugging performance issues. Note that when retries or redirects happen, the time spent in each layer is cumulative, as noted by the [layer]_count. The metrics are stored in the Request.context dictionary, and can be accessed like HTTP.get(...).request.context

Retry arguments:

retry = true, retry idempotent requests in case of error.
retries = 4, number of times to retry.
retry_non_idempotent = false, retry non-idempotent requests too. e.g. POST.
retry_delays = ExponentialBackOff(n = retries), provide a custom ExponentialBackOff object to control the delay between retries.
retry_check = (s, ex, req, resp, resp_body) -> Bool, provide a custom function to control whether a retry should be attempted. The function should accept 5 arguments: the delay state, exception, request, response (an HTTP.Response object if a request was successfully made, otherwise nothing), and resp_body response body (which may be nothing if there is no response yet, otherwise a Vector{UInt8}), and return true if a retry should be attempted.

Redirect arguments:

redirect = true, follow 3xx redirect responses; i.e. additional requests will be made to the redirected location
redirect_limit = 3, maximum number of times a redirect will be followed
redirect_method = nothing, the method to use for the redirected request; by default, GET will be used, only responses with 307/308 will use the same original request method. Pass redirect_method=:same to pass the same method as the orginal request though note that some servers may not respond/accept the same method. It's also valid to pass the exact method to use as a string, like redirect_method="PUT".
forwardheaders = true, forward original headers on redirect.

SSL arguments:

require_ssl_verification = NetworkOptions.verify_host(host), pass MBEDTLS_SSL_VERIFY_REQUIRED to the mbed TLS library. "... peer must present a valid certificate, handshake is aborted if verification failed."
sslconfig = SSLConfig(require_ssl_verification)
socket_type_tls = MbedTLS.SSLContext, the type of socket to use for TLS connections. Defaults to MbedTLS.SSLContext. Also supported is passing socket_type_tls = OpenSSL.SSLStream. To change the global default, set HTTP.SOCKET_TYPE_TLS[] = OpenSSL.SSLStream.

Cookie arguments:

cookies::Union{Bool, Dict{<:AbstractString, <:AbstractString}} = true, enable cookies, or alternatively, pass a Dict{AbstractString, AbstractString} of name-value pairs to manually pass cookies in the request "Cookie" header
cookiejar::HTTP.CookieJar=HTTP.COOKIEJAR: threadsafe cookie jar struct for keeping track of cookies per host; a global cookie jar is used by default.

Request Body Examples

String body:

HTTP.request("POST", "http://httpbin.org/post", [], "post body data")

Stream body from file:

io = open("post_data.txt", "r")
HTTP.request("POST", "http://httpbin.org/post", [], io)

Generator body:

chunks = ("chunk$i" for i in 1:1000)
HTTP.request("POST", "http://httpbin.org/post", [], chunks)

Collection body:

chunks = [preamble_chunk, data_chunk, checksum(data_chunk)]
HTTP.request("POST", "http://httpbin.org/post", [], chunks)

open() do io body:

HTTP.open("POST", "http://httpbin.org/post") do io
    write(io, preamble_chunk)
    write(io, data_chunk)
    write(io, checksum(data_chunk))
end

Response Body Examples

String body:

r = HTTP.request("GET", "http://httpbin.org/get")
println(String(r.body))

Stream body to file:

io = open("get_data.txt", "w")
r = HTTP.request("GET", "http://httpbin.org/get", response_stream=io)
close(io)
println(read("get_data.txt"))

Stream body through buffer:

r = HTTP.get("http://httpbin.org/get", response_stream=IOBuffer())
println(String(take!(r.body)))

Stream body through open() do io:

r = HTTP.open("GET", "http://httpbin.org/stream/10") do io
   while !eof(io)
       println(String(readavailable(io)))
   end
end

HTTP.open("GET", "https://tinyurl.com/bach-cello-suite-1-ogg") do http
    n = 0
    r = startread(http)
    l = parse(Int, HTTP.header(r, "Content-Length"))
    open(`vlc -q --play-and-exit --intf dummy -`, "w") do vlc
        while !eof(http)
            bytes = readavailable(http)
            write(vlc, bytes)
            n += length(bytes)
            println("streamed $n-bytes $((100*n)÷l)%\u1b[1A")
        end
    end
end

Interfacing with RESTful JSON APIs:

using JSON
params = Dict("user"=>"RAO...tjN", "token"=>"NzU...Wnp", "message"=>"Hello!")
url = "http://api.domain.com/1/messages.json"
r = HTTP.post(url, body=JSON.json(params))
println(JSON.parse(String(r.body)))

Stream bodies from and to files:

in = open("foo.png", "r")
out = open("foo.jpg", "w")
HTTP.request("POST", "http://convert.com/png2jpg", [], in, response_stream=out)

Stream bodies through: open() do io:

HTTP.open("POST", "http://music.com/play") do io
    write(io, JSON.json([
        "auth" => "12345XXXX",
        "song_id" => 7,
    ]))
    r = startread(io)
    @show r.status
    while !eof(io)
        bytes = readavailable(io)
        play_audio(bytes)
    end
end