Http.Extras

Convenience functions for creating HTTP requests and interpreting an HTTP response.

Requests

Helpers for creating HTTP requests.

type alias Request msg =

{ method : String

, headers : List Header

, url : String

, body : Body

, expect : Expect msg

, timeout : Maybe Float

, tracker : Maybe String

}

The type that needs to be passed into Http.request. It's never actually defined as a type in elm/http, so this is just the type definition for it.

listToHeaders : List ( String, String ) -> List Header

Convenience function to generate a list of Http.Headers from a List ( String, String ).

listToHeaders [ ( "Max-Forwards", "10" ), ( "Authorization", "Basic pw123" ) ]
    == [ Http.Header "Max-Forwards" "10", Http.Header "Authorization" "Basic pw123" ]

listToQuery : List ( String, String ) -> String

Convenience function to generate a percent-encoded query string from a List ( String, String ). The string includes the ? at the beginning.

listToQuery [ ( "foo", "abc 123" ), ( "bar", "xyz" ) ]
    == "?foo=abc%20123&bar=xyz"

Note: A more appropriate place for this function would probably be a package like Url.Extras. However, such a package doesn't exist, and I use this function quite frequently, so I've included it here.

Responses

Helpers for interpreting an Http.Response value.

Transform

Transform an Http.Response value into the respective Result that is returned in each expect function from elm/http. Used for building custom expect functions.

For example, you could replicate Http.expectString like so:

import Http
import Http.Extras


expectString : (Result Http.Error String -> msg) -> Http.Expect msg
expectString toMsg =
    Http.expectStringResponse toMsg Http.Extras.responseToString

responseToString : Response String -> Result Error String

responseToJson : Decoder a -> Response String -> Result Error a

responseToBytes : Decoder a -> Response Bytes -> Result Error a

responseToWhatever : Response Bytes -> Result Error ()

Getters

Convenience functions for extracting information like the header, status code, url, etc. from a Http.Response value. On an error, a short string will be returned describing why the error occurred. For example:

getStatusCode Http.Timeout_
    == Err "Timeout"

These functions are primarily concerned with accessing the metadata of a response. So, these functions will return a successful Result if the response is GoodStatus_ or BadStatus_. Otherwise, the Result will be an error.

getUrl : Response body -> Result String String

Note that this only tries to return the url from the metadata - it does not return the url if the response is BadUrl_

getStatusCode : Response body -> Result String Int

getStatusText : Response body -> Result String String

getHeaders : Response body -> Result String (Dict String String)

getMetadata : Response body -> Result String Metadata

getBody : Response body -> Result String body

isSuccess : Response body -> Result String Int

Returns the status code if 200 <= status code < 300

Miscellaneous

type State success error

= NotRequested

| Fetching

| Success success

| Error error

A custom type for keeping track of the state of a HTTP requests in your program's Model. This is just a suggested pattern to use in your development. It's included primarily for my own convenience - here's an example of how it would be used.

type alias Model =
    { apiCats : State ( CatsResponseType, Http.Metadata ) (Http.Detailed.Error String)
    }


type Msg =
    APICatsResponse
    | ...


init =
    ( { apiCats = NotRequested }, Cmd.none )


update msg model =
    case msg of
        APICatsResponse httpResponse ->
            case httpResponse of
                Ok (response, metadata) ->
                    ( { model | apiCats = Success (response, metadata) }
                    , Cmd.none )


                Err httpError ->
                    ( { model | apiCats = Error httpError }
                    , Cmd.none )


    ...

Note: It's been brought to my attention that this is the almost the exact same thing as the popular RemoteData - when I created this package, I had never heard about RemoteData, yet I had been using the same design pattern.

I will leave this type here to avoid breaking API changes, but I would recommend checking out RemoteData - it integrates fairly easily with this package. It offers a lot of handy helper functions too!

To replicate their WebData type, you would use something like so:

type alias WebDataDetailed err success =
    RemoteData (Http.Detailed.Error err) success

jzxhuang/http-extras/1.0.2