[ { "name": "Http.Progress", "comment": " Track the progress of an HTTP request. This can be useful if you are\nrequesting a large amount of data and want to show the user a progress bar\nor something.\n\nHere is an example usage: [demo][] and [code][].\n\n[demo]: https://hirafuji.com.br/elm/http-progress-example/\n[code]: https://gist.github.com/pablohirafuji/fa373d07c42016756d5bca28962008c4\n\n**Note:** If you stop tracking progress, you cancel the request.\n\n# Progress\n@docs Progress, track\n\n", "unions": [ { "name": "Progress", "comment": " The progress of an HTTP request.\n\nYou start with `None`. As data starts to come in, you will see `Some`. The\n`bytesExpected` field will match the `Content-Length` header, indicating how\nlong the response body is in bytes (8-bits). The `bytes` field indicates how\nmany bytes have been loaded so far, so if you want progress as a percentage,\nyou would say:\n\n Some { bytes, bytesExpected } ->\n toFloat bytes / toFloat bytesExpected\n\nYou will end up with `Fail` or `Done` depending on the success of the request.\n", "args": [ "data" ], "cases": [ [ "None", [] ], [ "Some", [ "{ bytes : Int, bytesExpected : Int }" ] ], [ "Fail", [ "Error" ] ], [ "Done", [ "data" ] ] ] } ], "aliases": [], "values": [ { "name": "track", "comment": " Create a subscription that tracks the progress of an HTTP request.\n\nSee it in action in this example: [demo][] and [code][].\n\n[demo]: https://hirafuji.com.br/elm/http-progress-example/\n[code]: https://gist.github.com/pablohirafuji/fa373d07c42016756d5bca28962008c4\n", "type": "String -> (Progress data -> msg) -> Request data -> Sub msg" } ], "binops": [] }, { "name": "Http", "comment": " Create and send HTTP requests.\n\n# Send Requests\n@docs Request, send, Error\n\n# GET\n@docs getString, get\n\n# POST\n@docs post\n\n# Custom Requests\n@docs request\n\n## Headers\n@docs Header, header\n\n## Request Bodies\n@docs Body, emptyBody, jsonBody, stringBody, multipartBody, Part, stringPart\n\n## Responses\n@docs Expect, expectString, expectJson, expectStringResponse, Response\n\n# Low-Level\n@docs encodeUri, decodeUri, toTask\n\n", "unions": [ { "name": "Error", "comment": " A `Request` can fail in a couple ways:\n\n - `BadUrl` means you did not provide a valid URL.\n - `Timeout` means it took too long to get a response.\n - `NetworkError` means the user turned off their wifi, went in a cave, etc.\n - `BadStatus` means you got a response back, but the [status code][sc]\n indicates failure.\n - `BadPayload` means you got a response back with a nice status code, but\n the body of the response was something unexpected. The `String` in this\n case is a debugging message that explains what went wrong with your JSON\n decoder or whatever.\n\n[sc]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html\n", "args": [], "cases": [ [ "BadUrl", [ "String" ] ], [ "Timeout", [] ], [ "NetworkError", [] ], [ "BadStatus", [ "Response String" ] ], [ "BadPayload", [ "String", "Response String" ] ] ] }, { "name": "Part", "comment": " Contents of a multi-part body. Right now it only supports strings, but we\nwill support blobs and files when we get an API for them in Elm.\n", "args": [], "cases": [] } ], "aliases": [ { "name": "Body", "comment": " Represents the body of a `Request`.\n", "args": [], "type": "Body" }, { "name": "Expect", "comment": " Logic for interpreting a response body.\n", "args": [ "a" ], "type": "Expect a" }, { "name": "Header", "comment": " An HTTP header for configuring requests. See a bunch of common headers\n[here][].\n\n[here]: https://en.wikipedia.org/wiki/List_of_HTTP_header_fields\n", "args": [], "type": "Header" }, { "name": "Request", "comment": " Describes an HTTP request.\n", "args": [ "a" ], "type": "Request a" }, { "name": "Response", "comment": " The response from a `Request`.\n", "args": [ "body" ], "type": "{ url : String, status : { code : Int, message : String }, headers : Dict String String, body : body }" } ], "values": [ { "name": "decodeUri", "comment": " Use this to unescape query parameters. It converts things like `%2F` to\n`/`. It can fail in some cases. For example, there is no way to unescape `%`\nbecause it could never appear alone in a properly escaped string.\n\nIt works just like `decodeURIComponent` in JavaScript.\n", "type": "String -> Maybe String" }, { "name": "emptyBody", "comment": " Create an empty body for your `Request`. This is useful for GET requests\nand POST requests where you are not sending any data.\n", "type": "Body" }, { "name": "encodeUri", "comment": " Use this to escape query parameters. Converts characters like `/` to `%2F`\nso that it does not clash with normal URL\n\nIt work just like `encodeURIComponent` in JavaScript.\n", "type": "String -> String" }, { "name": "expectJson", "comment": " Expect the response body to be JSON. You provide a `Decoder` to turn that\nJSON into an Elm value. If the body cannot be parsed as JSON or if the JSON\ndoes not match the decoder, the request will resolve to a `BadPayload` error.\n", "type": "Decoder a -> Expect a" }, { "name": "expectString", "comment": " Expect the response body to be a `String`.\n", "type": "Expect String" }, { "name": "expectStringResponse", "comment": " Maybe you want the whole `Response`: status code, headers, body, etc. This\nlets you get all of that information. From there you can use functions like\n`Json.Decode.decodeString` to interpret it as JSON or whatever else you want.\n", "type": "(Response String -> Result String a) -> Expect a" }, { "name": "get", "comment": " Create a `GET` request and try to decode the response body from JSON to\nsome Elm value.\n\n import Http\n import Json.Decode exposing (list, string)\n\n getBooks : Http.Request (List String)\n getBooks =\n Http.get \"https://example.com/books\" (list string)\n\nYou can learn more about how JSON decoders work [here][] in the guide.\n\n[here]: https://guide.elm-lang.org/interop/json.html\n", "type": "String -> Decoder a -> Request a" }, { "name": "getString", "comment": " Create a `GET` request and interpret the response body as a `String`.\n\n import Http\n\n getWarAndPeace : Http.Request String\n getWarAndPeace =\n Http.getString \"https://example.com/books/war-and-peace\"\n", "type": "String -> Request String" }, { "name": "header", "comment": " Create a `Header`.\n\n header \"If-Modified-Since\" \"Sat 29 Oct 1994 19:43:31 GMT\"\n header \"Max-Forwards\" \"10\"\n header \"X-Requested-With\" \"XMLHttpRequest\"\n\n**Note:** In the future, we may split this out into an `Http.Headers` module\nand provide helpers for cases that are common on the client-side. If this\nsounds nice to you, open an issue [here][] describing the helper you want and\nwhy you need it.\n\n[here]: https://github.com/elm-lang/http/issues\n", "type": "String -> String -> Header" }, { "name": "jsonBody", "comment": " Put some JSON value in the body of your `Request`. This will automatically\nadd the `Content-Type: application/json` header.\n", "type": "Value -> Body" }, { "name": "multipartBody", "comment": " Create multi-part bodies for your `Request`, automatically adding the\n`Content-Type: multipart/form-data` header.\n", "type": "List Part -> Body" }, { "name": "post", "comment": " Create a `POST` request and try to decode the response body from JSON to\nan Elm value. For example, if we want to send a POST without any data in the\nrequest body, it would be like this:\n\n import Http\n import Json.Decode exposing (list, string)\n\n postBooks : Http.Request (List String)\n postBooks =\n Http.post \"https://example.com/books\" Http.emptyBody (list string)\n\nSee [`jsonBody`](#jsonBody) to learn how to have a more interesting request\nbody. And check out [this section][here] of the guide to learn more about\nJSON decoders.\n\n[here]: https://guide.elm-lang.org/interop/json.html\n\n", "type": "String -> Body -> Decoder a -> Request a" }, { "name": "request", "comment": " Create a custom request. For example, a custom PUT request would look like\nthis:\n\n put : String -> Body -> Request ()\n put url body =\n request\n { method = \"PUT\"\n , headers = []\n , url = url\n , body = body\n , expect = expectStringResponse (\\_ -> Ok ())\n , timeout = Nothing\n , withCredentials = False\n }\n", "type": "{ method : String, headers : List Header, url : String, body : Body, expect : Expect a, timeout : Maybe Time, withCredentials : Bool } -> Request a" }, { "name": "send", "comment": " Send a `Request`. We could get the text of “War and Peace” like this:\n\n import Http\n\n type Msg = Click | NewBook (Result Http.Error String)\n\n update : Msg -> Model -> Model\n update msg model =\n case msg of\n Click ->\n ( model, getWarAndPeace )\n\n NewBook (Ok book) ->\n ...\n\n NewBook (Err _) ->\n ...\n\n getWarAndPeace : Cmd Msg\n getWarAndPeace =\n Http.send NewBook <|\n Http.getString \"https://example.com/books/war-and-peace.md\"\n", "type": "(Result Error a -> msg) -> Request a -> Cmd msg" }, { "name": "stringBody", "comment": " Put some string in the body of your `Request`. Defining `jsonBody` looks\nlike this:\n\n import Json.Encode as Encode\n\n jsonBody : Encode.Value -> Body\n jsonBody value =\n stringBody \"application/json\" (Encode.encode 0 value)\n\nNotice that the first argument is a [MIME type][mime] so we know to add\n`Content-Type: application/json` to our request headers. Make sure your\nMIME type matches your data. Some servers are strict about this!\n\n[mime]: https://en.wikipedia.org/wiki/Media_type\n", "type": "String -> String -> Body" }, { "name": "stringPart", "comment": " A named chunk of string data.\n\n body =\n multipartBody\n [ stringPart \"user\" \"tom\"\n , stringPart \"payload\" \"42\"\n ]\n", "type": "String -> String -> Part" }, { "name": "toTask", "comment": " Convert a `Request` into a `Task`. This is only really useful if you want\nto chain together a bunch of requests (or any other tasks) in a single command.\n", "type": "Request a -> Task Error a" } ], "binops": [] } ]