NoRedInk / http-upgrade-shim / Http.Legacy

Create and send HTTP requests.

This is a shim version of the elm/http 1.0.0 API, including its documentation. Copyright (c) 2016-present, Evan Czaplicki.

The purpose of this module is to allow a smooth upgrade to version 2.x of elm/http without requiring a large amount of changes across the codebase.

Send Requests


type alias Request a =
{ method : String
, headers : List Http.Header
, url : String
, body : Http.Body
, expect : Expect a
, timeout : Maybe Basics.Float
, withCredentials : Basics.Bool 
}

Describes an HTTP request.

send : (Result Error a -> msg) -> Request a -> Platform.Cmd.Cmd msg

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"


type Error
    = BadUrl String
    | Timeout
    | NetworkError
    | BadStatus (Response String)
    | BadPayload String (Response String)

A Request can fail in a couple ways:

GET

getString : String -> Request String

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.

get : String -> Json.Decode.Decoder a -> Request a

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.

POST

post : String -> Body -> Json.Decode.Decoder a -> Request a

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.

Custom Requests

request : { method : String, headers : List Header, url : String, body : Body, expect : Expect a, timeout : Maybe Basics.Float, withCredentials : Basics.Bool } -> Request a

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.

Headers


type alias Header =
Http.Header

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

header : String -> String -> Header

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.

Request Bodies


type alias Body =
Http.Body

Represents the body of a Request.

emptyBody : Body

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

jsonBody : Json.Encode.Value -> Body

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

stringBody : String -> String -> Body

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!

multipartBody : List Part -> Body

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


type alias Part =
Http.Part

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.

stringPart : String -> String -> Part

A named chunk of string data.

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

Responses


type alias Expect a =
{ expect : Http.Expect (Result Error (Response String))
, decode : Response String -> Result Error a 
}

Logic for interpreting a response body.

expectString : Expect String

Expect the response body to be a String.

expectJson : Json.Decode.Decoder a -> Expect a

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.

expectStringResponse : (Response String -> Result String a) -> Expect a

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.


type alias Response body =
{ url : String
, status : { code : Basics.Int
, message : String }
, headers : Dict String String
, body : body 
}

The response from a Request.

Low-Level

toTask : Request a -> Task Error a

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.

Helpers for use during the elm/http 2.0.0 upgrade

toHttp2Error : Error -> Http.Error

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.