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.
{ 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"
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.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 : 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.
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.
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.
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.
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"
]
{ 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.
{ url : String
, status : { code : Basics.Int
, message : String }
, headers : Dict String String
, body : body
}
The response from a Request
.
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.
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.