EngageSoftware / elm-dnn-http / Engage.Http

Helpers for working with DNN Web API

Types


type alias Config =
{ baseUrl : String
, headers : List Http.Header 
}

Configuration type


type Error
    = BadUrl String
    | Timeout
    | NetworkError
    | BadStatus Basics.Int String
    | BadBody String

When a request fails, the Failure value will be one of these. Most of these are copied from Http.Error in the elm/http module.

When there is a BadStatus, both the status code and the body of the response are included. This allows getErrorMessage to retrieve any error message in the response, if they are available.

HTTP Verbs

get : Config -> (RemoteData Error success -> msg) -> Json.Decode.Decoder success -> { methodName : String, queryStringParams : List ( String, String ) } -> Platform.Cmd.Cmd msg

HTTP GET

post : Config -> (RemoteData Error success -> msg) -> Json.Decode.Decoder success -> { methodName : String, value : Json.Encode.Value } -> Platform.Cmd.Cmd msg

HTTP POST

patch : Config -> (RemoteData Error success -> msg) -> Json.Decode.Decoder success -> { methodName : String, value : Json.Encode.Value } -> Platform.Cmd.Cmd msg

HTTP PATCH

put : Config -> (RemoteData Error success -> msg) -> Json.Decode.Decoder success -> { methodName : String, value : Json.Encode.Value } -> Platform.Cmd.Cmd msg

HTTP PUT

delete : Config -> (RemoteData Error success -> msg) -> Json.Decode.Decoder success -> { methodName : String, value : Json.Encode.Value } -> Platform.Cmd.Cmd msg

HTTP DELETE

Raw requests

requestJson : String -> List Http.Header -> String -> Http.Body -> (RemoteData Error success -> msg) -> Json.Decode.Decoder success -> Platform.Cmd.Cmd msg

Raw request that expects a JSON response.

This version can use any method and accepts any body (e.g. Http.fileBody, Http.bytesBody, or Http.emptyBody).

requestString : String -> List Http.Header -> String -> Http.Body -> (RemoteData Error success -> msg) -> (Http.Metadata -> String -> Result Error success) -> Platform.Cmd.Cmd msg

Raw request that expects a String response (but not necessarily a valid JSON String).

This version can use any method and accepts any body (e.g. Http.fileBody, Http.bytesBody, or Http.emptyBody). Additionally, instead of providing a Json.Decode.Decoder to handle the response, you provide a function which can transform the String response body (and response metadata) however you need.

requestAnything : String -> List Http.Header -> String -> Http.Body -> (RemoteData Error () -> msg) -> Platform.Cmd.Cmd msg

Raw request that does not expect a response.

This version can use any method and accepts any body (e.g. Http.fileBody, Http.bytesBody, or Http.emptyBody).

requestBytes : String -> List Http.Header -> String -> Http.Body -> (RemoteData Error Bytes -> msg) -> Platform.Cmd.Cmd msg

Raw request that expects a Bytes response.

This version can use any method and accepts any body (e.g. Http.fileBody, Http.bytesBody, or Http.emptyBody).

Helper functions

getErrorMessage : { a | localization : Engage.Localization.Localization } -> Error -> String

Get the localized error message from the Error

import Dict
import Engage.Localization as Localization exposing (Localization)

type alias Model =
    { localization : Localization }

model : Model
model =
    Model Localization.empty

decodeError : Engage.Http.Error
decodeError =
    Engage.Http.BadBody "Problem with the given value: null Expecting an INT"

Engage.Http.getErrorMessage model decodeError
--> "Problem with the given value: null Expecting an INT"

errorFromServer : Engage.Http.Error
errorFromServer =
    Engage.Http.BadStatus 404 """ { "Message": "The requested item wasn't found" } """

Engage.Http.getErrorMessage model errorFromServer
--> "The requested item wasn't found"

localizedModel : Model
localizedModel =
    Dict.fromList
        [ ( "NetworkError.Text", "The network had an issue" )
        , ( "Server.Error", "The server had an issue" )
        ]
        |> Localization.fromDict
        |> Model

statusError : Engage.Http.Error
statusError =
    Engage.Http.BadStatus 404 """ 404 Error response """

Engage.Http.getErrorMessage localizedModel statusError
--> "The server had an issue"

Engage.Http.getErrorMessage localizedModel Engage.Http.NetworkError
--> "The network had an issue"

urlWithQueryString : String -> String -> List ( String, String ) -> String

Get the full URL from a base URL, a method name (i.e. a route), and query string values.

The function adds a trailing slash to the base URL if missing. Query string values are URL encoded.

config : Engage.Http.Config
config =
    { baseUrl = "https://example.com/API/MyModule"
    , headers = []
    }

Engage.Http.urlWithQueryString config.baseUrl "" []
--> "https://example.com/API/MyModule/"

Engage.Http.urlWithQueryString config.baseUrl "health" []
--> "https://example.com/API/MyModule/health"

Engage.Http.urlWithQueryString config.baseUrl "articles" [ ( "page", "1" ) ]
--> "https://example.com/API/MyModule/articles?page=1"

Engage.Http.urlWithQueryString config.baseUrl "author" [ ( "name", "Joël Quenneville" ) ]
--> "https://example.com/API/MyModule/author?name=Jo%C3%ABl%20Quenneville"

Decoders

configDecoder : Json.Decode.Decoder Config

Json decoder for Config

import Http
import Json.Decode as Decode

"""
{
    "baseUrl": "/API/MyModule/Search",
    "headers": {
        "ModuleId": "100",
        "TabId": "404"
    }
}
"""
    |> Decode.decodeString Engage.Http.configDecoder
--> Ok { baseUrl = "/API/MyModule/Search", headers = [ Http.header "ModuleId" "100", Http.header "TabId" "404" ] }

serverErrorDecoder : { a | localization : Engage.Localization.Localization } -> Json.Decode.Decoder String

JSON decoder for server error, localized.

The error comes from a string field named "ExceptionMessage", "exceptionMessage", "Message", "message", or otherwise multipleServerErrorDecoder.

multipleServerErrorDecoder : { a | localization : Engage.Localization.Localization } -> Json.Decode.Decoder String

JSON decoder for multiple server error messages, localized.

The messages come from a string array field named "ExceptionMessage", "exceptionMessage", "Messages", or "message". These values are then concatenated with spaces.

nullDecoder : Json.Decode.Decoder ()

Null decoder. Useful for when the server doesn't return any value.