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, Cmd Msg )
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.Legacy as Http


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

Note: Use elm/url to build URLs.

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.

Note: Use elm/url to build URLs.

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
        }

The timeout is the number of milliseconds you are willing to wait before giving up.

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.

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.

Convert an error from this module to the original Http module type. This function leaks the current implementation using the elm/http 1.0.0 API, so every place outside of this module we need to use this indicates a spot that will require a bit of massaging when we upgrade to version 2.0.0.