httpstan: Auto-generated httpstan API Client

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]


Client library for calling the httpstan API based on http-client.

host: localhost

base path: http://localhost

httpstan API version: 4.10.0

OpenAPI version: 3.0.1

[Skip to Readme]


Change log None available
Dependencies aeson (>=1.0 && <3.0), base (>=4.7 && <5.0), base64-bytestring (>1.0 && <2.0), bytestring (>=0.10.0), case-insensitive, containers (>= && <0.8), deepseq (>=1.4 && <1.6), exceptions (>=0.4), http-api-data (>=0.3.4 && <0.5), http-client (>=0.5 && <0.8), http-client-tls, http-media (>=0.4 && <0.9), http-types (>=0.8 && <0.13), iso8601-time (>=0.1.3 && <0.2.0), katip (>=0.8 && <1.0), microlens (>=0.4.3), mtl (>=2.2.1), network (>=2.6.2 && <3.9), random (>=1.1), safe-exceptions (<0.2), text (>=0.11 && <1.3), time (>=1.5), transformers (>=, unordered-containers, vector (>=0.10.9 && <0.13) [details]
License BSD-3-Clause
Copyright 2023 - Jake McArthur
Author Jake McArthur
Category Statistics
Home page
Source repo head: git clone
Uploaded by JakeMcArthur at 2023-05-29T17:56:10Z



Manual Flags


Use the katip package to provide logging (if false, use the default monad-logger package)


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for httpstan-

[back to package description]

OpenAPI Auto-Generated http-client Bindings to httpstan

The library in lib provides auto-generated-from-OpenAPI http-client bindings to the httpstan API.

OpenApi Version: 3.0.1


Installation follows the standard approach to installing Stack-based projects.

  1. Install the Haskell stack tool.
  2. To build the package, and generate the documentation (recommended):
stack haddock

which will generate docs for this lib in the docs folder.

To generate the docs in the normal location (to enable hyperlinks to external libs), remove

    - "--odir=./docs"

from the stack.yaml file and run stack haddock again.

  1. To run unit tests:
stack test


The code generator that produced this library, and which explains how to obtain and use the openapi-generator cli tool lives at

The generator-name argument (--generator-name) passed to the cli tool used should be


Unsupported OpenAPI Features

This is beta software; other cases may not be supported.

Codegen "additional properties" parameters

These options allow some customization of the code generation process.

haskell-http-client additional properties:

allowFromJsonNulls allow JSON Null during model decoding from JSON true true
allowNonUniqueOperationIds allow different API modules to contain the same operationId. Each API must be imported qualified false false
allowToJsonNulls allow emitting JSON Null during model encoding to JSON false false
baseModule Set the base module namespace Httpstan
cabalPackage Set the cabal package name, which consists of one or more alphanumeric words separated by hyphens httpstan
cabalVersion Set the cabal version number, consisting of a sequence of one or more integers separated by dots
customTestInstanceModule test module used to provide typeclass instances for types not known by the generator
configType Set the name of the type used for configuration HttpstanConfig
dateFormat format string used to parse/render a date %Y-%m-%d %Y-%m-%d
dateTimeFormat format string used to parse/render a datetime. (Defaults to formatISO8601Millis when not provided)
dateTimeParseFormat overrides the format string used to parse a datetime
generateEnums Generate specific datatypes for OpenAPI enums true true
generateFormUrlEncodedInstances Generate FromForm/ToForm instances for models used by x-www-form-urlencoded operations (model fields must be primitive types) true true
generateLenses Generate Lens optics for Models true true
generateModelConstructors Generate smart constructors (only supply required fields) for models true true
inlineMimeTypes Inline (hardcode) the content-type and accept parameters on operations, when there is only 1 option true true
modelDeriving Additional classes to include in the deriving() clause of Models
requestType Set the name of the type used to generate requests HttpstanRequest
strictFields Add strictness annotations to all model fields true true
useKatip Sets the default value for the UseKatip cabal flag. If true, the katip package provides logging instead of monad-logger true true
queryExtraUnreserved Configures additional querystring characters which must not be URI encoded, e.g. '+' or ':'

An example setting dateTimeFormat and strictFields:

java -jar openapi-generator-cli.jar generate -i petstore.yaml -g haskell-http-client -o output/haskell-http-client --additional-properties=dateTimeFormat="%Y-%m-%dT%H:%M:%S%Q%z" --additional-properties=strictFields=false

View the full list of Codegen "config option" parameters with the command:

java -jar openapi-generator-cli.jar config-help -g haskell-http-client

Usage Notes

Example Petstore Haddock documentation

An example of the generated haddock documentation targeting the server (Petstore) can be found here

Example Petstore App

An example application using the auto-generated haskell-http-client bindings for the server can be found here

This library is intended to be imported qualified.


Httpstan.Client use the "dispatch" functions to send requests
Httpstan.Core core functions, config and request types
Httpstan.API construct api requests
Httpstan.Model describes api models
Httpstan.MimeTypes encoding/decoding MIME types (content-types/accept)
Httpstan.ModelLens lenses for model fields
Httpstan.Logging logging functions and utils


This library adds type safety around what OpenAPI specifies as Produces and Consumes for each Operation (e.g. the list of MIME types an Operation can Produce (using 'accept' headers) and Consume (using 'content-type' headers).

For example, if there is an Operation named addFoo, there will be a data type generated named AddFoo (note the capitalization), which describes additional constraints and actions on the addFoo operation via its typeclass instances. These typeclass instances can be viewed in GHCi or via the Haddocks.

Example code generated for pretend addFoo operation:

data AddFoo
instance Consumes AddFoo MimeJSON
instance Produces AddFoo MimeJSON
instance Produces AddFoo MimeXML
instance HasBodyParam AddFoo FooModel
instance HasOptionalParam AddFoo FooName
instance HasOptionalParam AddFoo FooId

this would indicate that:

If the OpenAPI spec doesn't declare it can accept or produce a certain MIME type for a given Operation, you should either add a Produces or Consumes instance for the desired MIME types (assuming the server supports it), use dispatchLbsUnsafe or modify the OpenAPI spec and run the generator again.

New MIME type instances can be added via MimeType/MimeRender/MimeUnrender

Only JSON instances are generated by default, and in some case x-www-form-urlencoded instances (FromFrom, ToForm) will also be generated if the model fields are primitive types, and there are Operations using x-www-form-urlencoded which use those models.


A haskell data type will be generated for each OpenAPI authentication type.

If for example the AuthMethod AuthOAuthFoo is generated for OAuth operations, then addAuthMethod should be used to add the AuthMethod config.

When a request is dispatched, if a matching auth method is found in the config, it will be applied to the request.


mgr <- newManager defaultManagerSettings
config0 <- withStdoutLogging =<< newConfig
let config = config0
    `addAuthMethod` AuthOAuthFoo "secret-key"

let addFooRequest =
    (ContentType MimeJSON)
    (Accept MimeXML)
    (ParamBar paramBar)
    (ParamQux paramQux)
  `applyOptionalParam` FooId 1
  `applyOptionalParam` FooName "name"
  `setHeader` [("qux_header","xxyy")]
addFooResult <- dispatchMime mgr config addFooRequest

See the example app and the haddocks for details.