{"id":27876378,"url":"https://github.com/jzxhuang/http-extras","last_synced_at":"2025-05-05T02:48:00.298Z","repository":{"id":62418678,"uuid":"160650099","full_name":"jzxhuang/http-extras","owner":"jzxhuang","description":"Improved HTTP in Elm - detailed responses, convenience functions and API mocking.","archived":false,"fork":false,"pushed_at":"2020-02-13T03:24:40.000Z","size":50,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2023-08-08T20:39:29.276Z","etag":null,"topics":["api","api-client","elm","http","library","mock","testing"],"latest_commit_sha":null,"homepage":"https://package.elm-lang.org/packages/jzxhuang/http-extras/latest/","language":"Elm","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jzxhuang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-06T09:21:24.000Z","updated_at":"2022-05-31T06:05:20.000Z","dependencies_parsed_at":"2022-11-01T16:46:38.061Z","dependency_job_id":null,"html_url":"https://github.com/jzxhuang/http-extras","commit_stats":null,"previous_names":[],"tags_count":7,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzxhuang%2Fhttp-extras","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzxhuang%2Fhttp-extras/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzxhuang%2Fhttp-extras/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzxhuang%2Fhttp-extras/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jzxhuang","download_url":"https://codeload.github.com/jzxhuang/http-extras/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252429966,"owners_count":21746570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","elm","http","library","mock","testing"],"created_at":"2025-05-05T02:47:59.830Z","updated_at":"2025-05-05T02:48:00.282Z","avatar_url":"https://github.com/jzxhuang.png","language":"Elm","funding_links":[],"categories":[],"sub_categories":[],"readme":"# http-extras\n\nThree modules to help you work with HTTP in Elm. More detailed responses, convenience functions, and API mocking.\n\nMade for use with version **2.0+** of [`elm/http`][http].\n\n## Detailed\n\n[`elm/http`][http] discards the metadata and original body of an HTTP response, even though they are often useful.\n\nFor example, maybe your server returns a useful error message that you want to try and decode, or store an auth token in the header of a response.\n\nThis module lets you create HTTP requests that return more detailed responses - responses that keep useful information around instead of throwing them away!\n\n_I wrote a [guide explaining how to extract detailed information from HTTP responses in Elm,][Going Beyond 200 OK] both with and without this package. Giving it a read might help you better understand the motivation and use cases behind this module!_\n\n## Extras\n\nA collection of convenience and utility functions for creating HTTP requests and working with HTTP responses.\n\nFor example, there are helpers to...\n\n* Convert a `List ( String, String )` to a percent-encoded query string or `List Http.Header`\n* Extract information like the header, status code, url, etc. from an [`Http.Response`][httpResponse]\n* Transform an [`Http.Response`][httpResponse] into the `Result` used by [`elm/http`][http].\n\n## Mock\n\nEasily mock the response of your API from within Elm. Don't bother setting up fake servers that mock responses.\n\nVery useful for testing your code. Make sure it's robust enough to handle any type of response, including edge cases like a request that results in a `Timeout`.\n\n_I wrote a [guide discussing HTTP mocking in Elm][Oh the mockery], both with and without this package. Giving it a read might help you better understand the motivation and use cases behind this module!_\n\n## Example\n\nHere's a complete example of how you might use all the modules in this package together. See each module's documentation for more specific examples!\n\n```elm\nimport Http\nimport Http.Detailed\nimport Http.Extras\nimport Http.Mock\nimport Json.Decode exposing (Decoder, field, string, list)\n\n\ntype Msg\n    = GotGif (Result (Http.Detailed.Error String) ( Http.Metadata, String ))\n    | GotItems (Result (Http.Detailed.Error String) ( Http.Metadata, List String ))\n\n\n-- Build a request with query parameters and a detailed response\n\n\ngetRandomCatGif : List ( String, String ) -\u003e Cmd Msg\ngetRandomCatGif queries =\n    Http.get\n        { url = \"https://api.giphy.com/v1/gifs/random\" ++ Http.Extras.listToQuery queries\n        , expect = Http.Detailed.expectJson GotGif gifDecoder\n\n\n-- Mock a timeout response\n\n\nfetchItemsMockingTimeout : Cmd Msg\nfetchItemsMockingTimeout =\n    Http.post\n        { url = \"https://fakeurl.com/items.json\"\n        , body = Http.emptyBody\n        , expect =\n            Http.Mock.expectStringResponse Http.Timeout_ GotItems \u003c|\n                Http.Detailed.responseToJson itemsDecoder\n        }\n\n\n-- Decoders\n\n\ngifDecoder : Decoder String\ngifDecoder =\n    field \"data\" (field \"image_url\" string)\n\n\nitemsDecoder : Decoder (List String)\nitemsDecoder =\n    list (field \"name\" string)\n\n\n-- Update\n\n\nupdate : Msg -\u003e Model -\u003e ( Model, Cmd Msg )\nupdate msg model =\n    case msg of\n        GotGif detailedResponse -\u003e\n            case detailedResponse of\n                Ok ( metadata, gif ) -\u003e\n                    -- Success! Do something with the metadata if you need\n\n                Err error -\u003e\n                    case error of\n                        Http.Detailed.BadStatus metadata body -\u003e\n                            -- Maybe the error message is useful and you want to try and decode the body\n\n                        ...\n\n        GotItems detailedResponse -\u003e\n            case detailedResponse of\n                Ok ( metadata, items ) -\u003e\n                    -- Success! Do something with the metadata if you need\n\n                Err error -\u003e\n                    case error of\n                        Http.Detailed.Timeout -\u003e\n                            -- We mock a Timeout response - make sure your code handles this case correctly!\n\n                        ...\n\n        ...\n\n```\n\nIn this example:\n\n* We use [`Detailed`](/Http-Detailed) to create HTTP requests that return more detailed responses. In our `update` function, you can access these extra details like the metadata and use them as needed.\n* The GIF request uses [`Extras`](/Http-Extras) to build a request with a query string.\n* The Items request uses [`Mock`](/Http-Mock) to mock a `Timeout` response.\n\n## Contributing\n\nFeedback and contributions are very welcome! Open an issue or pull request on Github as appropriate.\n\n## License\n\nHTTP-Extras is available under the [BSD-3-Clause License][bsd]. See LICENSE on the Github repo for details.\n\n[http]: https://package.elm-lang.org/packages/elm/http/2.0.0\n[httpResponse]: https://package.elm-lang.org/packages/elm/http/2.0.0/Http#Response\n[bsd]: https://opensource.org/licenses/BSD-3-Clause\n[Going Beyond 200 OK]: https://medium.com/@jzxhuang/going-beyond-200-ok-a-guide-to-detailed-http-responses-in-elm-6ddd02322e\n[Oh the Mockery]: https://medium.com/@jzxhuang/oh-the-mockery-a-guide-to-http-mocking-in-elm-f625c2a56c9f\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjzxhuang%2Fhttp-extras","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjzxhuang%2Fhttp-extras","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjzxhuang%2Fhttp-extras/lists"}