Describes an HTTP request.

Send a Request. We could get the text of “War and Peace” like this:

import Http


type Msg = Click | NewBook (Result Http.Error String)


update : Msg -> Model -> Model
update msg model =
  case msg of
    Click ->
      ( model, getWarAndPeace )


    NewBook (Ok book) ->
      ...


    NewBook (Err _) ->
      ...


getWarAndPeace : Cmd Msg
getWarAndPeace =
  Http.send NewBook <|
    Http.getString "https://example.com/books/war-and-peace.md"

A Request can fail in a couple ways:

• BadUrl means you did not provide a valid URL.
• Timeout means it took too long to get a response.
• NetworkError means the user turned off their wifi, went in a cave, etc.
• BadStatus means you got a response back, but the status code indicates failure.
• BadPayload means you got a response back with a nice status code, but the body of the response was something unexpected. The String in this case is a debugging message that explains what went wrong with your JSON decoder or whatever.

Create a GET request and interpret the response body as a String.

import Http


getWarAndPeace : Http.Request String
getWarAndPeace =
  Http.getString "https://example.com/books/war-and-peace"

Create a GET request and try to decode the response body from JSON to some Elm value.

import Http
import Json.Decode exposing (list, string)


getBooks : Http.Request (List String)
getBooks =
  Http.get "https://example.com/books" (list string)

You can learn more about how JSON decoders work here in the guide.

Create a POST request and try to decode the response body from JSON to an Elm value. For example, if we want to send a POST without any data in the request body, it would be like this:

import Http
import Json.Decode exposing (list, string)


postBooks : Http.Request (List String)
postBooks =
  Http.post "https://example.com/books" Http.emptyBody (list string)

See jsonBody to learn how to have a more interesting request body. And check out this section of the guide to learn more about JSON decoders.

Create a custom request. For example, a custom PUT request would look like this:

put : String -> Body -> Request ()
put url body =
  request
    { method = "PUT"
    , headers = []
    , url = url
    , body = body
    , expect = expectStringResponse (\_ -> Ok ())
    , timeout = Nothing
    , withCredentials = False
    }

An HTTP header for configuring requests. See a bunch of common headers here.

Create a Header.

header "If-Modified-Since" "Sat 29 Oct 1994 19:43:31 GMT"
header "Max-Forwards" "10"
header "X-Requested-With" "XMLHttpRequest"

Note: In the future, we may split this out into an Http.Headers module and provide helpers for cases that are common on the client-side. If this sounds nice to you, open an issue here describing the helper you want and why you need it.

Represents the body of a Request.

Create an empty body for your Request. This is useful for GET requests and POST requests where you are not sending any data.

Put some JSON value in the body of your Request. This will automatically add the Content-Type: application/json header.

Put some string in the body of your Request. Defining jsonBody looks like this:

import Json.Encode as Encode


jsonBody : Encode.Value -> Body
jsonBody value =
  stringBody "application/json" (Encode.encode 0 value)

Notice that the first argument is a MIME type so we know to add Content-Type: application/json to our request headers. Make sure your MIME type matches your data. Some servers are strict about this!

Create multi-part bodies for your Request, automatically adding the Content-Type: multipart/form-data header.

Contents of a multi-part body. Right now it only supports strings, but we will support blobs and files when we get an API for them in Elm.

A named chunk of string data.

body =
  multipartBody
    [ stringPart "user" "tom"
    , stringPart "payload" "42"
    ]

Logic for interpreting a response body.

Expect the response body to be a String.

Expect the response body to be JSON. You provide a Decoder to turn that JSON into an Elm value. If the body cannot be parsed as JSON or if the JSON does not match the decoder, the request will resolve to a BadPayload error.

Maybe you want the whole Response: status code, headers, body, etc. This lets you get all of that information. From there you can use functions like Json.Decode.decodeString to interpret it as JSON or whatever else you want.

The response from a Request.

Use this to escape query parameters. Converts characters like / to %2F so that it does not clash with normal URL

It work just like encodeURIComponent in JavaScript.

Use this to unescape query parameters. It converts things like %2F to /. It can fail in some cases. For example, there is no way to unescape % because it could never appear alone in a properly escaped string.

It works just like decodeURIComponent in JavaScript.

Convert a Request into a Task. This is only really useful if you want to chain together a bunch of requests (or any other tasks) in a single command.