This module contains several functions that build on the
elm-lang/http package.
Note that interpretStatus
and promoteError
are no longer included, because
the Http
module now does what they used to do.
For new projects, I would recommend using lukewestby/elm-http-builder instead of this package. It is capable of doing everything this package does, and more.
{ method : String
, headers : List Http.Header
, url : String
, body : Http.Body
, expect : Http.Expect a
, timeout : Maybe Basics.Float
, withCredentials : Basics.Bool
}
The Request
type in the Http
module
is opaque, in the sense that once you have a Request
, you cannot extract its
parts in order to construct a different Request
. The RawRequest
type is a
workaround for that, allowing you to work with the parts of a request.
You can construct a RawRequest
manually, by filling in its parts. The various parts
have the same meaning as the parameters to Http.request
.
req : RawRequest String
req =
{ method = "GET"
, headers = [ header "X-Test-Header" "Foo" ]
, url = "http://elm-lang.org"
, body = Http.emptyBody
, expect = Http.expectString
, timeout = Nothing
, withCredentials = False
}
Alternatively, you can construct a RawRequest
by using defaultGet
,
defaultGetString
, or defaultPost
to fill in
some defaults. These functions are like Http.get
,
Http.getString
and
Http.post
, except that they return a
RawRequest
which you can further customize, rather than an opaque
Request
.
req : RawRequest String
req =
let
default =
defaultGetString "http://elm-lang.org"
in
{ default | headers = [ header "X-Test-Header" "Foo" ] }
Once you have a RawRequest
, you can use toRequest
to turn it into a
Request
that the Http
module can use.
Alternatively, you can sendRaw
or
toTaskRaw
to turn the RawRequest
directly into a Cmd
or Task
.
defaultPost : String -> Http.Body -> Json.Decode.Decoder a -> RawRequest a
Like Http.post
, but returns
a RawRequest
that you could further customize.
You can then use toRequest
to make an actual
Http.Request
, or supply
the RawRequest
to sendRaw
or toTaskRaw
.
defaultGet : String -> Json.Decode.Decoder a -> RawRequest a
Like Http.get
, but returns a
RawRequest String
that you could further customize.
You can then use toRequest
to make an actual
Http.Request
, or supply
the RawRequest
to sendRaw
or toTaskRaw
.
defaultGetString : String -> RawRequest String
Like Http.getString
, but returns
a RawRequest String
that you could further customize.
You can then use toRequest
to make an actual
Http.Request
, or supply
the RawRequest
to sendRaw
or toTaskRaw
.
req : RawRequest String
req =
let
default =
defaultGet "http://elm-lang.org"
in
{ default | timeout = Just (1 * Time.second) }
sendRaw : (Result Http.Error a -> msg) -> RawRequest a -> Platform.Cmd.Cmd msg
Like Http.send
,
but uses a RawRequest
instead of a
Request
.
toTaskRaw : RawRequest a -> Task Http.Error a
Like Http.toTask
,
but uses a RawRequest
instead of a
Request
.
toRequest : RawRequest a -> Http.Request a
Turns a RawRequest a
into an
Http.Request a
.
This is just another name for
Http.request
.
cacheBusterUrl : String -> Task x String
Given a URL, add a 'cache busting' parameter of the form '?cacheBuster=219384729384', where the number is derived from the current time. The purpose of doing this would be to help defeat any caching that might otherwise take place at some point between the client and server.
Often you won't need to call this directly -- you can use addCacheBuster
,
taskWithCacheBuster
or sendWithCacheBuster
instead.
urlWithTime : Task x String
urlWithTime =
cacheBusterUrl "http://elm-lang.org"
-- Should resolve to something like "http://elm-lang.org?param=7&cacheBuster=12348257"
urlWithTime2 : Task x String
urlWithTime2 =
cacheBusterUrl "http://elm-lang.org?param=7"
addCacheBuster : RawRequest a -> Task x (RawRequest a)
Given a RawRequest
, add a cache-busting parameter to the URL. This uses
cacheBusterUrl
internally to generate the parameter.
Note that the resulting task will resolve with the modified RawRequest
, which
will itself need to be turned into a Task
or Cmd
to be actually executed.
Thus, you often would not need to call this directly -- you could use
taskWithCacheBuster
or sendWithCacheBuster
instead. You would only need addCacheBuster
in cases where you need to do some
further processing of the resolved RawRequest
before turning it into a Task
or a Cmd
.
taskWithCacheBuster : RawRequest a -> Task Http.Error a
Given a RawRequest
, add a cache-busting parameter to the URL and return
a Task
that executes the request.
This is useful in cases where the resulting Task
is part of some larger
chain of tasks. In cases where you are just going to turn this very Task
into a Cmd
, you could use sendWithCacheBuster
instead.
sendWithCacheBuster : (Result Http.Error a -> msg) -> RawRequest a -> Platform.Cmd.Cmd msg
Given a RawRequest
, add a cache-busting parameter to the URL and return
a Cmd
that executes the request.
This is a convenience for cases in which your RawRequest
is meant to result
in a simple Cmd
. For more complex cases, you can use taskWithCacheBuster
,
addCacheBuster
or cacheBusterUrl
, depending
on how much further customization you need.