Awesome Open Source
Awesome Open Source


Hackage MIT license Build status


Hreq is a high-level easy to use type-driven HTTP client library inspired by Servant-Client. Hreq provides an alternative approach to type-safe construction and interpretation of API endpoints for Http client requests.

The Hreq github repository is a mono-repo composed of the following:

  • hreq-core implementing core functionality.

  • hreq-client an HTTP client using hreq-core functionality

  • hreq-conduit an HTTP client with streaming support via conduit.

Checkout accompanying blog post and minimal tutorial for more details


Hreq was motivated by the simplicity and ease of use of req and the type driven elegance of servant-client. I envisioned Hreq as the best possible compromise of both worlds.

Some of the Key Points

  • A default HTTP client manager is set up within the library such that one doesn't have to think about manager configuration.

  • Hreq provides type synonyms for common API type combinators, therefore, reducing on API types verbosity.

  • In Hreq, API types are used directly within API functions via Type Application while in servant-client API types create new API functions for creating API requests.

  • In Hreq, API Request component arguments are provided to the API function through a Heterogeneous list.

  • Hreq supports the concept of Retry policy, whereby an http request is retried automatically on network connection failure based on a set Retry policy.

Usage Example

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TypeApplications #-}
{-# LANGUAGE DeriveAnyClass #-}
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE DataKinds  #-}

module Main where

import Data.Aeson (FromJSON, ToJSON)
import GHC.Generics (Generic)
import Hreq.Client

data User = User
  { name :: String
  , age  :: Int
  } deriving (Show, Generic, FromJSON, ToJSON)

main' :: IO ()
main' = do
  res <- runHreq baseUrl $ do
    -- | Makes Post request with newUser as a request body
    createdUser <- createUser newUser
    -- | Makes Get Request with "allan" as a URL fragment
    myUser      <- getUserByName "allan"
    -- | Makes a Get Request returning a list of Users
    allUsers    <- hreq @(GetJson [User]) Empty
    return (createdUser, myUser, allUsers)
  print res
    baseUrl :: BaseUrl
    baseUrl = HttpDomain ""

    newUser :: User
    newUser = User "Allan" 29

createUser :: RunClient m => User -> m User
createUser user = hreq @(JsonBody User :> PostJson User) (user :. Empty)

getUserByName :: RunClient m => String -> m User
getUserByName userName = hreq @(Capture String :> GetJson User) (userName :. Empty)


Hreq is heavily inspired by servant-client and ideas from Serv.


This README is tested by markdown-unlit to make sure the code builds. To keep that happy, we do need a main in this file, so ignore the following :)

main :: IO ()
main = pure ()

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Haskell (32,287
Network (3,578
Http Client (1,254
Haskell Library (219
Related Projects