Req
HTML & web
Outbound HTTP for the BEAM, in the spirit of Elixir's Req.
Server listens. Req calls out. Use sync get / post / … from Mix-style CLI.* tasks (selm increment) or from request handlers. Browser apps use Http from the client platform.
Req.get "http://127.0.0.1:3000/count" []
Req.post "http://127.0.0.1:3000/items"
[ Req.header "authorization" token
, Req.json { title = "hi" }
]A successful round-trip is always Ok, including 4xx / 5xx. Transport failures (bad URL, timeout, connection refused) are Err.
For large responses, prefer stream and fold with Stream.tryFoldl / Stream.stoppableFoldl on the calling process. Closing the stream cancels the underlying request.
Types
Response
type alias Response =
{ statusCode : Int
, headers : List (String, String)
, body : String
, bodyBytes : Bytes
}One response from a completed HTTP round-trip.
body is the response as a UTF-8 string view of the bytes. bodyBytes is the raw body for binary APIs.
Examples
case Req.get "http://127.0.0.1:3000/count" [] of
Ok { statusCode, body } ->
body
Err err ->
errorToString errStreamResponse
type alias StreamResponse =
{ statusCode : Int
, headers : List (String, String)
, body : Stream Bytes
}Headers plus a lazy byte stream for the response body.
OTP httpc only streams status **200** and **206**; for those, statusCode is 206 when a content-range header is present, otherwise 200. Other statuses still return here with the real code and a finite (often one-chunk) body stream.
Examples
Req.stream "http://127.0.0.1:3000/export" []Error
type Error
= BadUrl String
| Timeout
| NetworkError StringWhy an outbound call never got a response.
Examples
BadUrl "ftp://x"
Timeout
NetworkError "econnrefused"Setting
type Setting = SettingOne request option (header, body, json, timeout, method, …).
Examples
header "authorization" tokenPart
type Part = PartOne part of a multipartBody.
Examples
stringPart "title" "hi"Values
get
get : String -> List Setting -> Result Error ResponseGET url.
Examples
get "http://127.0.0.1:3000/count" []post
post : String -> List Setting -> Result Error ResponsePOST url.
Examples
post "http://127.0.0.1:3000/items" [ json { title = "hi" } ]put
put : String -> List Setting -> Result Error ResponsePUT url.
Examples
put "http://127.0.0.1:3000/items/1" [ json { title = "x" } ]delete
delete : String -> List Setting -> Result Error ResponseDELETE url.
Examples
delete "http://127.0.0.1:3000/items/1" []request
request : String -> List Setting -> Result Error ResponseRequest with an explicit method (or method in the settings list).
Defaults to GET when no method is set.
Examples
request "http://127.0.0.1:3000/x" [ method "PATCH", json { n = 1 } ]stream
stream : String -> List Setting -> Result Error StreamResponseLike request, but returns the body as a Stream Bytes.
Consume on the same process that called stream. Prefer Stream.tryFoldl / Stream.stoppableFoldl. Discarding the stream cancels the HTTP request.
Examples
stream "http://127.0.0.1:3000/export" []header
header : String -> String -> SettingAdd a request header.
Examples
header "authorization" "Bearer tok"body
body : String -> SettingSet a raw request body (and default content-type to text/plain unless a content-type header is already present).
Examples
body "hello"bytesBody
bytesBody : Bytes -> SettingSet a binary request body (default content-type application/octet-stream unless overridden).
Examples
bytesBody bytesformBody
formBody : List (String, String) -> SettingEncode application/x-www-form-urlencoded fields and set the body.
Keys and values are percent-encoded. Sets content-type unless a content-type header is already present.
Examples
formBody [ ( "q", "hat" ), ( "page", "1" ) ]json
json : a -> SettingEncode a value as JSON (thoas), set the body, and use application/json unless a content-type header is already present.
Examples
json { title = "hi" }multipartBody
multipartBody : List Part -> SettingBuild a multipart/form-data body from parts and set the matching content-type (unless a content-type header is already present).
Examples
multipartBody [ stringPart "title" "hi", filePart "file" "/tmp/a.csv" ]stringPart
stringPart : String -> String -> PartA text form field.
Examples
stringPart "title" "hi"bytesPart
bytesPart : String -> String -> Bytes -> PartA binary file field with an explicit MIME type (filename blob).
Examples
bytesPart "file" "text/csv" bytesfilePart
filePart : String -> String -> PartA file field read from a filesystem path at send time.
Filename is the path basename; MIME type is application/octet-stream.
Examples
filePart "file" "/tmp/a.csv"timeout
timeout : Int -> SettingRequest timeout in milliseconds (default 30000).
Examples
timeout 5000method
method : String -> SettingOverride the HTTP method for request / stream (for example "PATCH").
Examples
method "PATCH"followRedirects
followRedirects : Bool -> SettingFollow 3xx redirects via httpc (False by default).
Examples
followRedirects Trueretry
retry : Int -> SettingExtra attempts after a transport failure (timeout / network). 0 means one try total. For stream, retries only apply before response headers arrive.
Examples
retry 2errorToString
errorToString : Error -> StringHuman-readable form of an Error for CLI / logs.
Examples
errorToString Timeout == "timeout"