Module "http"

Creates the effect manager.

Create a GET request.

    import Http
    type Msg
      = GotText (Result Http.Error String)
    getPublicOpinion : Cmd Msg
    getPublicOpinion =
      Http.get
        { url = "https://elm-lang.org/assets/public-opinion.txt"
        , expect = Http.expectString GotText
        }

You can use functions like [expectString]{@link module:Http.expectString} and [expectJson]{@link module:Http.expectJson} to interpret the response in different ways. In this example, we are expecting the response body to be a String containing the full text of Public Opinion by Walter Lippmann. Note: Use elm/url to build reliable URLs.

Create a POST request. So imagine we want to send a POST request for some JSON data. It might look like this:

    import Http
    import Json.Decode exposing (list, string)
    type Msg
      = GotBooks (Result Http.Error (List String))
    postBooks : Cmd Msg
    postBooks =
      Http.post
        { url = "https://example.com/books"
        , body = Http.emptyBody
        , expect = Http.expectJson GotBooks (list string)
        }

Notice that we are using expectJson to interpret the response as JSON. You can learn more about how JSON decoders work [here][] in the guide. We did not put anything in the body of our request, but you can use functions like stringBody and jsonBody if you need to send information to the server. [here]: https://guide.elm-lang.org/interop/json.html

Create a custom request. For example, a PUT for files might look like this:

  import File
  import Http
  type Msg = Uploaded (Result Http.Error ())
  upload : File.File -> Cmd Msg
  upload file =
    Http.request
      { method = "PUT"
      , headers = []
      , url = "https://example.com/publish"
      , body = Http.fileBody file
      , expect = Http.expectWhatever Uploaded
      , timeout = Nothing
      , tracker = Nothing
      }

It lets you set custom headers as needed. The timeout is the number of milliseconds you are willing to wait before giving up. The tracker lets you cancel and track requests.

Expect valid json but do not care about the contents. Probably not a good idea as skipping checking the contents may cause hard to debug runtime exceptions further ahead.

Expect the response body to be binary data. For example, maybe you are talking to an endpoint that gives back ProtoBuf data:

    import Bytes.Decode as Bytes
    import Http
    type Msg
      = GotData (Result Http.Error Data)
    getData : Cmd Msg
    getData =
      Http.get
        { url = "/data"
        , expect = Http.expectBytes GotData dataDecoder
        }
    -- dataDecoder : Bytes.Decoder Data

You would use elm/bytes to decode the binary data according to a proto definition file like example.proto. If the decoder fails, you get a BadBody error that just indicates that something went wrong. It probably makes sense to debug by peeking at the bytes you are getting in the browser developer tools or something.

Expect the response body to be JSON. Like if you want to get a random cat GIF you might say:

    import Http
    import Json.Decode exposing (Decoder, field, string)
    type Msg
      = GotGif (Result Http.Error String)
    getRandomCatGif : Cmd Msg
    getRandomCatGif =
      Http.get
        { url = "https://api.giphy.com/v1/gifs/random?api_key=dc6zaTOxFJmzC&tag=cat"
        , expect = Http.expectJson GotGif gifDecoder
        }
    gifDecoder : Decoder String
    gifDecoder =
      field "data" (field "image_url" string)

The official guide goes through this particular example [here][]. That page also introduces [elm/json][json] to help you get started turning JSON into Elm values in other situations. [here]: https://guide.elm-lang.org/interop/json.html [json]: /packages/elm/json/latest/ If the JSON decoder fails, you get a BadBody error that tries to explain what went wrong.

Expect the response body to be a String. Like when getting the full text of a book:

    import Http
    type Msg
      = GotText (Result Http.Error String)
    getPublicOpinion : Cmd Msg
    getPublicOpinion =
      Http.get
        { url = "https://elm-lang.org/assets/public-opinion.txt"
        , expect = Http.expectString GotText
        }

The response body is always some sequence of bytes, but in this case, we expect it to be UTF-8 encoded text that can be turned into a String.

Expect the response body to be whatever. It does not matter. Ignore it! For example, you might want this when uploading files:

    import Http
    type Msg
      = Uploaded (Result Http.Error ())
    upload : File -> Cmd Msg
    upload file =
      Http.post
        { url = "/upload"
        , body = Http.fileBody file
        , expect = Http.expectWhatever Uploaded
        }

The server may be giving back a response body, but we do not care about it.

Track the progress of a request. Create a request where tracker = Just "form.pdf" and you can track it with a subscription like track "form.pdf" GotProgress.

Try to cancel an ongoing request based on a tracker.

Expect a Response with a Bytes body. It works just like expectStringResponse, giving you more access to headers and more leeway in defining your own errors.

Expect a Response with a String body. So you could define your own expectJson like this:

    import Http
    import Json.Decode as D
    expectJson : (Result Http.Error a -> msg) -> D.Decoder a -> Expect msg
    expectJson toMsg decoder =
      expectStringResponse toMsg <|
        \response ->
          case response of
            Http.BadUrl_ url ->
              Err (Http.BadUrl url)
            Http.Timeout_ ->
              Err Http.Timeout
            Http.NetworkError_ ->
              Err Http.NetworkError
            Http.BadStatus_ metadata body ->
              Err (Http.BadStatus metadata.statusCode)
            Http.GoodStatus_ metadata body ->
              case D.decodeString decoder body of
                Ok value ->
                  Ok value
                Err err ->
                  BadBody (D.errorToString err)

This function is great for fancier error handling and getting response headers. For example, maybe when your sever gives a 404 status code (not found) it also provides a helpful JSON message in the response body. This function lets you add logic to the BadStatus_ branch so you can parse that JSON and give users a more helpful message! Or make your own custom error type for your particular application!