ohanhi / remotedata-http / RemoteData.Http

Friendly abstraction over remote API communication in JSON.

Commands

get : String -> (RemoteData.WebData success -> msg) -> Json.Decode.Decoder success -> Platform.Cmd.Cmd msg

GET request as a command. Has a no-cache header to ensure data integrity.

type Msg
    = HandleGetCat (WebData Cat)

getCat : Cmd Msg
getCat =
    get "/api/cats/1" HandleGetCat catDecoder

post : String -> (RemoteData.WebData success -> msg) -> Json.Decode.Decoder success -> Json.Encode.Value -> Platform.Cmd.Cmd msg

POST request as a command.

type Msg
    = HandlePostCat (WebData Cat)

postCat : Cat -> Cmd Msg
postCat cat =
    post "/api/cats/" HandlePostCat catDecoder (encodeCat cat)

put : String -> (RemoteData.WebData success -> msg) -> Json.Decode.Decoder success -> Json.Encode.Value -> Platform.Cmd.Cmd msg

PUT request as a command.

type Msg
    = HandlePutCat (WebData Cat)

putCat : Cat -> Cmd Msg
putCat cat =
    put "/api/cats/" HandlePutCat catDecoder (encodeCat cat)

patch : String -> (RemoteData.WebData success -> msg) -> Json.Decode.Decoder success -> Json.Encode.Value -> Platform.Cmd.Cmd msg

PATCH request as a command.

type Msg
    = HandlePatchCat (WebData Cat)

patchCat : Cat -> Cmd Msg
patchCat cat =
    patch "/api/cats/" HandlePatchCat catDecoder (encodeCat cat)

delete : String -> (RemoteData.WebData String -> msg) -> Json.Encode.Value -> Platform.Cmd.Cmd msg

DELETE request as a command, expecting a String response.

In many APIs, the response for successful delete requests has an empty HTTP body, so decoding it as JSON will always fail. This is why delete and deleteTask don't have a decoder argument. If you really want to decode the response, use Json.Decode.decodeString.

type Msg
    = HandleDeleteCat (WebData String)

deleteCat : Cat -> Cmd Msg
deleteCat cat =
    delete "/api/cats/" HandleDeleteCat (encodeCat cat)

Helpful headers

noCache : Http.Header

Header that makes sure the response doesn't come from a cache. Only relevant for GET requests.

acceptJson : Http.Header

Header for explicitly stating we are expecting JSON back.

Commands with configuration


type alias Config =
{ headers : List Http.Header
, timeout : Maybe Basics.Float
, tracker : Maybe String
, risky : Basics.Bool 
}

If you need more control over the request, you can use the <verb>WithConfig function with a record like this.

specialConfig : Config
specialConfig =
    { defaultConfig | headers = [ specialHeader, anotherHeader ] }

postCat : Cat -> Cmd Msg
postCat cat =
    postWithConfig specialConfig "/api/cats/" HandlePostCat catDecoder (encodeCat cat)

defaultConfig : Config

The default configuration for all requests besides GET:

noCacheConfig : Config

The default configuration for GET requests:

getWithConfig : Config -> String -> (RemoteData.WebData success -> msg) -> Json.Decode.Decoder success -> Platform.Cmd.Cmd msg

GET request as a command, with cache. NB. allowing cache in API GET calls can lead to strange conditions.

getWithConfig noCacheConfig "http://example.com/users.json" userDecoder
    == get "http://example.com/users.json" userDecoder

For a request without any headers, you can use:

getWithConfig defaultConfig url decoder

postWithConfig : Config -> String -> (RemoteData.WebData success -> msg) -> Json.Decode.Decoder success -> Json.Encode.Value -> Platform.Cmd.Cmd msg

POST request as a command, with additional Config.

postWithConfig defaultConfig == post

putWithConfig : Config -> String -> (RemoteData.WebData success -> msg) -> Json.Decode.Decoder success -> Json.Encode.Value -> Platform.Cmd.Cmd msg

PUT request as a command, with additional Config.

putWithConfig defaultConfig == putTask

patchWithConfig : Config -> String -> (RemoteData.WebData success -> msg) -> Json.Decode.Decoder success -> Json.Encode.Value -> Platform.Cmd.Cmd msg

PATCH request as a command, with additional Config.

patchWithConfig defaultConfig == patchTask

deleteWithConfig : Config -> String -> (RemoteData.WebData String -> msg) -> Json.Encode.Value -> Platform.Cmd.Cmd msg

DELETE request as a command, with additional Config.

deleteWithConfig defaultConfig == deleteTask

Tasks

These should be rather rarely used.

getTask : String -> Json.Decode.Decoder success -> Task () (RemoteData.WebData success)

GET request as a task. Has a no-cache header to ensure data integrity.

getCatTask : Task () (WebData Cat)
getCatTask =
    getTask "/api/cats/1" catDecoder

postTask : String -> Json.Decode.Decoder success -> Json.Decode.Value -> Task () (RemoteData.WebData success)

POST request as a task.

postCatTask : Cat -> Task () (WebData Cat)
postCatTask cat =
    postTask "/api/cats/" catDecoder (encodeCat cat)

putTask : String -> Json.Decode.Decoder success -> Json.Decode.Value -> Task () (RemoteData.WebData success)

PUT request as a task.

putCatTask : Cat -> Task () (WebData Cat)
putCatTask cat =
    putTask "/api/cats/" catDecoder (encodeCat cat)

patchTask : String -> Json.Decode.Decoder success -> Json.Decode.Value -> Task () (RemoteData.WebData success)

PATCH request as a task.

patchCatTask : Cat -> Task () (WebData Cat)
patchCatTask cat =
    patchTask "/api/cats/" catDecoder (encodeCat cat)

deleteTask : String -> Json.Decode.Value -> Task () (RemoteData.WebData String)

DELETE request as a task, expecting a String response. In many APIs, the response for successful delete requests has an empty HTTP body, so decoding it as JSON will always fail. This is why delete and deleteTask don't have a decoder argument. If you really want to decode the response, use Json.Decode.decodeString.

deleteCatTask : Cat -> Task () (WebData String)
deleteCatTask cat =
    deleteTask "/api/cats/" (encodeCat cat)

Tasks with configuration


type alias TaskConfig =
{ headers : List Http.Header
, timeout : Maybe Basics.Float
, risky : Basics.Bool 
}

If you need more control over the request, you can use the <verb>TaskWithConfig function with a record like this.

specialConfig : TaskConfig
specialConfig =
    { defaultConfig | headers = [ specialHeader, anotherHeader ] }

postCatTask cat =
    postTaskWithConfig specialConfig "/api/cats/" HandlePostCat catDecoder (encodeCat cat)

defaultTaskConfig : TaskConfig

The default configuration for all requests besides GET:

noCacheTaskConfig : TaskConfig

The default configuration for GET requests:

getTaskWithConfig : TaskConfig -> String -> Json.Decode.Decoder success -> Task () (RemoteData.WebData success)

GET request as a task, with additional Config. NB. allowing cache in API GET calls can lead to strange conditions.

getTaskWithConfig noCacheConfig "http://example.com/users.json" userDecoder
    == getTask "http://example.com/users.json" userDecoder

For a request without any headers, you can use:

getTaskWithConfig defaultTaskConfig url decoder

postTaskWithConfig : TaskConfig -> String -> Json.Decode.Decoder success -> Json.Encode.Value -> Task () (RemoteData.WebData success)

POST request as a task, with additional Config.

postTaskWithConfig defaultTaskConfig == postTask

putTaskWithConfig : TaskConfig -> String -> Json.Decode.Decoder success -> Json.Encode.Value -> Task () (RemoteData.WebData success)

PUT request as a task, with additional Config.

putTaskWithConfig defaultTaskConfig == putTask

patchTaskWithConfig : TaskConfig -> String -> Json.Decode.Decoder success -> Json.Encode.Value -> Task () (RemoteData.WebData success)

PATCH request as a task, with additional Config.

patchTaskWithConfig defaultTaskConfig == patchTask

deleteTaskWithConfig : TaskConfig -> String -> Json.Decode.Value -> Task () (RemoteData.WebData String)

DELETE request as a task, with additional Config.

deleteTaskWithConfig defaultTaskConfig == deleteTask