arowM / tepa / Tepa.Http

Send HTTP requests.

Requests

get : { url : String } -> Tepa.Promise m (Response String)

Create a GET request.

import Tepa exposing (Promise)
import Tepa.Http as Http

myProcedures : Promise m ()
myProcedures =
    [ Debug.todo "some procedures"
    , Tepa.bind
        (Http.get
            { url = "https://elm-lang.org/assets/public-opinion.txt"
            }
        )
      <|
        \result ->
            case result of
                Err err ->
                    [ proceduresForFailure err
                    ]

                Ok content ->
                    [ proceduersForReceivingResponse content
                    ]
    ]

You can use functions like expectString exposed by elm/json to interpret the response as JSON value. In this example, we are expecting the response body to be a String containing the full text of Public Opinion by Walter Lippmann.

Note: Use elm/url to build reliable URLs.

post : { url : String, requestBody : RequestBody } -> Tepa.Promise m (Response String)

Create a POST request. So imagine we want to send a POST request for some JSON data. It might look like this:

import Json.Decode as JD
import Tepa exposing (Promise)
import Tepa.Http as Http

myProcedures : Promise m ()
myProcedures =
    [ Debug.todo "some procedures"
    , Tepa.bind
        (Http.post
            { url = "https://elm-lang.org/assets/public-opinion.txt"
            , requestBody = Http.EmptyRequestBody
            }
        )
      <|
        \result ->
            case result of
                GoodResponse meta rawBody ->
                    case JD.decodeString (JD.list JD.string) content of
                        Err err ->
                            [ proceduresForInvalidResponseBody err
                            ]

                        Ok body ->
                            [ proceduresForJsonResponseBody body
                            ]

                _ ->
                    defaultHttpHandler result
    ]

Notice that we are using decodeString to interpret the response as JSON.

We did not put anything in the body of our request, but you can use constructors for the RequestBody if you need to send information to the server.

request : { method : String, headers : List Header, url : String, requestBody : RequestBody, timeout : Maybe Basics.Int } -> Tepa.Promise m (Response String)

Create a custom request. For example, a PUT for files might look like this:

import File exposing (File)
import Tepa exposing (Promise)
import Tepa.Http as Http

type Msg
    = Uploaded (Result Http.Error ())

upload :
    File
    ->
        Promise
            c
            m
            (Result
                Http.Error
                ( Http.Metadata, String )
            )
upload file =
    request
        { method = "PUT"
        , headers = []
        , url = "https://example.com/publish"
        , requestBody = fileBody file
        , timeout = Nothing
        }

It lets you set custom headers as needed. The timeout is the number of milliseconds you are willing to wait before giving up.

bytesRequest : { method : String, headers : List Header, url : String, requestBody : RequestBody, timeout : Maybe Basics.Int } -> Tepa.Promise m (Response Bytes)

Header


type Header

An HTTP header for configuring requests.

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"

Request Body


type RequestBody

Represents the body of a request.

emptyBody : RequestBody

Create an empty body for your Request. This is useful for GET requests and POST requests where you are not sending any data.

stringBody : String -> String -> RequestBody

Put some string in the body of your request. Defining jsonRequest looks like this:

import Json.Encode as JE exposing (Value)

jsonBody : Value -> Body
jsonBody value =
    stringBody "application/json" (JE.encode 0 value)

The first argument is a MIME type of the body. Some servers are strict about this!

jsonBody : Json.Encode.Value -> RequestBody

Put some JSON value in the body of your request. This will automatically add the Content-Type: application/json header.

fileBody : File -> RequestBody

Use a file as the body of your request. When someone uploads an image into the browser with elm/file you can forward it to a server.

This will automatically set the Content-Type to the MIME type of the file.

Note: Use track to track upload progress.

bytesBody : String -> Bytes -> RequestBody

Put some Bytes in the body of your request. This allows you to use elm/bytes to have full control over the binary representation of the data you are sending. For example, you could create an archive.zip file and send it along like this:

import Bytes exposing (Bytes)

zipBody : Bytes -> RequestBody
zipBody bytes =
  bytesBody "application/zip" bytes

The first argument is a [MIME type](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the body. In other scenarios you may want to use MIME types like `image/png` or `image/jpeg` instead.

Note: Use track to track upload progress.

Response


type Response body
    = BadUrl String
    | Timeout
    | NetworkError
    | BadResponse Metadata body
    | GoodResponse Metadata body


type alias Metadata =
{ url : String
, statusCode : Basics.Int
, statusText : String
, headers : Dict String String 
}

Extra information about the response:

Note: It is possible for a response to have the same header multiple times. In that case, all the values end up in a single entry in the headers dictionary. The values are separated by commas, following the rules outlined here.