HttpBuilder

Extra helpers for more easily building Http requests that require greater configuration than what is provided by elm-http out of the box.

Start a request

type alias RequestBuilder a =

{ method : String

, headers : List Header

, url : String

, body : Body

, expect : Expect a

, timeout : Maybe Float

, withCredentials : Bool

, queryParams : List ( String, String )

, cacheBuster : Maybe String

}

A type for chaining request configuration

get : String -> RequestBuilder ()

Start building a GET request with a given URL

get "https://example.com/api/items/1"

post : String -> RequestBuilder ()

Start building a POST request with a given URL

post "https://example.com/api/items"

put : String -> RequestBuilder ()

Start building a PUT request with a given URL

put "https://example.com/api/items/1"

patch : String -> RequestBuilder ()

Start building a PATCH request with a given URL

patch "https://example.com/api/items/1"

delete : String -> RequestBuilder ()

Start building a DELETE request with a given URL

delete "https://example.com/api/items/1"

options : String -> RequestBuilder ()

Start building a OPTIONS request with a given URL

options "https://example.com/api/items/1"

trace : String -> RequestBuilder ()

Start building a TRACE request with a given URL

trace "https://example.com/api/items/1"

head : String -> RequestBuilder ()

Start building a HEAD request with a given URL

head "https://example.com/api/items/1"

Configure request properties

withHeader : String -> String -> RequestBuilder a -> RequestBuilder a

Add a single header to a request

get "https://example.com/api/items/1"
    |> withHeader "Content-Type" "application/json"

withHeaders : List ( String, String ) -> RequestBuilder a -> RequestBuilder a

Add many headers to a request

get "https://example.com/api/items/1"
    |> withHeaders [("Content-Type", "application/json"), ("Accept", "application/json")]

withBody : Body -> RequestBuilder a -> RequestBuilder a

Add an Http.Body to the request

post "https://example.com/api/save-text"
    |> withBody (Http.stringBody "text/plain" "Hello!")

withStringBody : String -> String -> RequestBuilder a -> RequestBuilder a

Convenience function for adding a string body to a request

post "https://example.com/api/items/1"
    |> withStringBody "application/json" """{ "sortBy": "coolness", "take": 10 }"""

withJsonBody : Value -> RequestBuilder a -> RequestBuilder a

Convenience function for adding a JSON body to a request

params = Json.Encode.object
    [ ("sortBy", Json.Encode.string "coolness")
    , ("take", Json.Encode.int 10)
    ]


post "https://example.com/api/items/1"
    |> withJsonBody params

withMultipartStringBody : List ( String, String ) -> RequestBuilder a -> RequestBuilder a

Convenience function for adding multipart bodies composed of String, String key-value pairs. Since Http.stringData is currently the only Http.Data creator having this function removes the need to use the Http.Data type in your type signatures.

post "https://example.com/api/items/1"
    |> withMultipartStringBody [("user", JS.encode user)]

withUrlEncodedBody : List ( String, String ) -> RequestBuilder a -> RequestBuilder a

Convenience function for adding url encoded bodies

post "https://example.com/api/whatever"
    |> withUrlEncodedBody [("user", "Luke"), ("pwd", "secret")]

withTimeout : Float -> RequestBuilder a -> RequestBuilder a

Set the timeout setting on the request

get "https://example.com/api/items/1"
    |> withTimeout (10 * Time.second)

withCredentials : RequestBuilder a -> RequestBuilder a

Set the withCredentials flag on the request to True. Works via XMLHttpRequest#withCredentials

get "https://example.com/api/items/1"
    |> withCredentials

withQueryParam : String -> String -> RequestBuilder a -> RequestBuilder a

Add a query param to the url for the request

get "https://example.com/api/items/1"
    |> withQueryParam "hello" "world"
-- sends a request to https://example.com/api/items/1?hello=world

withQueryParams : List ( String, String ) -> RequestBuilder a -> RequestBuilder a

Add some query params to the url for the request

get "https://example.com/api/items/1"
    |> withQueryParams [("hello", "world"), ("foo", "bar")]
    |> withQueryParams [("baz", "qux")]
-- sends a request to https://example.com/api/items/1?hello=world&foo=bar&baz=qux

withExpect : Expect b -> RequestBuilder a -> RequestBuilder b

Choose an Expect for the request

get "https://example.com/api/items/1"
    |> withExpect (Http.expectJson itemsDecoder)

withCacheBuster : String -> RequestBuilder a -> RequestBuilder a

Send the request with a Time based cache buster added to the URL. You provide a key for an extra query param, and when the request is sent that query param will be given a value with the current timestamp.

type Msg
    = Items (Result Http.Error String)


get "https://example.com/api/items"
    |> withExpect (Http.expectString)
    |> withCacheBuster "cache_buster"
    |> send Items


-- makes a request to https://example.com/api/items?cache_buster=1481633217383

withExpectJson : Decoder b -> RequestBuilder a -> RequestBuilder b

Choose a Json Expect for the request

get "https://example.com/api/items/1"
    |> withExpectJson itemsDecoder

withExpectString : RequestBuilder a -> RequestBuilder String

Choose a String Expect for the request

get "https://example.com/api/items/1"
    |> withExpectString

withBearerToken : String -> RequestBuilder a -> RequestBuilder a

Add a bearer token to a request

get "https://example.com/api/items/1"
    |> withBearerToken "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhIjoiYSJ9.MvhYYpYBuN1rUaV0GGnQGvr889zY0xSc20Lnt8nMTfE"

Make the request

toRequest : RequestBuilder a -> Request a

Extract the Http.Request component of the builder in case you want to use it directly. This function is lossy and will discard some of the extra stuff that HttpBuilder allows you to do.

Things that will be lost:

Attaching a cache buster to requests using withCacheBuster

toTask : RequestBuilder a -> Task Error a

Convert the RequestBuilder to a Task with all options applied. toTask differs from toRequest in that it retains all extra behavior allowed by HttpBuilder, including

Attaching a cache buster to requests using withCacheBuster

send : (Result Error a -> msg) -> RequestBuilder a -> Cmd msg

Send the request

Retreive data about the request

requestUrl : RequestBuilder a -> String

Convert the RequestBuilder to a string representation of the URL with all options applied.

Modules

HttpBuilder