| name | haskell-servant-client |
| description | Servant client API wrapper conventions with two-layer error handling. Use when generating HTTP clients from Servant APIs, wrapping external service APIs, or integrating servant-client with effectful. |
Servant Client Conventions (Two-Layer Error Pattern)
Two-Layer Error Type
- Always separate network errors from domain errors -- never flatten into one type
- Wrap
ClientError (network/HTTP) and domain-specific error (parsed from response body) as distinct constructors
- Derive
Generic, Show, Eq with deriving stock
- Add
NFData on all error types for deep evaluation
- Add
Exception on the top-level client error for IO interop
data SlackClientError
= ServantError ClientError
| SlackError ResponseSlackError
deriving stock (Eq, Generic, Show)
instance NFData SlackClientError
instance Exception SlackClientError
ResponseJSON Newtype
- Use
newtype ResponseJSON a = ResponseJSON (Either DomainError a) to parse API envelopes
- The custom
FromJSON instance checks the ok field and branches to error or payload parsing
- Use
unnestErrors to collapse Either ClientError (ResponseJSON a) into Response a
newtype ResponseJSON a = ResponseJSON (Either ResponseSlackError a)
unnestErrors :: Either ClientError (ResponseJSON a) -> Response a
Three-Tier API Organization
- Raw Servant clients (internal, suffixed with
_):