servant-client
Automatic derivation of querying functions for servant
Version on this page: | 0.20@rev:6 |
LTS Haskell 22.33: | 0.20@rev:6 |
Stackage Nightly 2024-09-07: | 0.20.2 |
Latest on Hackage: | 0.20.2 |
servant-client-0.20@sha256:96494bcc0672b7501e98c6d45628eae1fea6a29e6f6972da75b27107b2e85128,4911
Module documentation for 0.20
- Servant
servant-client
This library lets you automatically derive Haskell functions that let you query each endpoint of a servant webservice.
Example
{-# LANGUAGE DataKinds #-}
{-# LANGUAGE TypeOperators #-}
import Data.Proxy
import Data.Text
import Network.HTTP.Client (newManager, defaultManagerSettings)
import Servant.API
import Servant.Client
type Book = Text
type MyApi = "books" :> Get '[JSON] [Book] -- GET /books
:<|> "books" :> ReqBody '[JSON] Book :> Post '[JSON] Book -- POST /books
myApi :: Proxy MyApi
myApi = Proxy
-- 'client' allows you to produce operations to query an API from a client.
postNewBook :: Book -> ClientM Book
getAllBooks :: ClientM [Book]
(getAllBooks :<|> postNewBook) = client myApi
main :: IO ()
main = do
manager' <- newManager defaultManagerSettings
res <- runClientM getAllBooks (mkClientEnv manager' (BaseUrl Http "localhost" 8081 ""))
case res of
Left err -> putStrLn $ "Error: " ++ show err
Right books -> print books
Changes
The latest version of this document is on GitHub.
Changelog for servant
package contains significant entries for all core packages.
Package versions follow the Package Versioning Policy: in A.B.C, bumps to either A or B represent major versions.
0.20
-
Escape special chars in QueryParams. #1584 #1597
Escape special chars in QueryParam (
:@&=+$
) in servant-client. Note that this mean binary data will not work as is, and so reverts the functionality in #1432. -
Handle Cookies correctly for RunStreamingClient #1605 #1606
Makes
performWithStreamingRequest
take into consideration the CookieJar, which it previously didn’t. -
Fix the handling of multiple headers with the same name. #1666
servant-client no longer concatenates the values of response headers with the same name. This fixes an issue with parsing multiple
Set-Cookie
headers.
0.19
Significant changes
- Drop support for GHC < 8.6.
- Support GHC 9.0 (GHC 9.2 should work as well, but isn’t fully tested yet).
- Support Aeson 2 (#1475), which fixes a DOS vulnerability related to hash collisions.
- Add
NamedRoutes
combinator, making support for records first-class in Servant (#1388). - Add custom type errors for partially applied combinators (#1289, #1486).
- servant-client / servant-client-core / servant-http-streams: Fix erroneous behavior, where only 2XX status codes would be considered successful, irrelevant of the status parameter specified by the verb combinator. (#1469)
- servant-client / servant-client-core: Fix
Show
instance forServant.Client.Core.Request
. - servant-client / servant-client-core: Allow passing arbitrary binary data in Query parameters. (#1432).
Other changes
- Various version bumps.
0.18.3
Significant changes
- Add response header support to UVerb (#1420)
Other changes
- Support GHC-9.0.1.
- Bump
bytestring
,hspec
,http-client
andQuickCheck
dependencies.
0.18.2
Significant changes
- Support
Fragment
combinator.
0.18.1
Significant changes
- Union verbs
Other changes
- Bump “tested-with” ghc versions
0.18
Significant changes
- Support for ghc8.8 (#1318, #1326, #1327)
0.17
Significant changes
-
Add NoContentVerb #1028 #1219 #1228
The
NoContent
API endpoints should now useNoContentVerb
combinator. The API type changes are usually of the kind- :<|> PostNoContent '[JSON] NoContent + :<|> PostNoContent
i.e. one doesn’t need to specify the content-type anymore. There is no content.
-
Capture
can beLenient
#1155 #1156You can specify a lenient capture as
:<|> "capture-lenient" :> Capture' '[Lenient] "foo" Int :> GET
which will make the capture always succeed. Handlers will be of the type
Either String CapturedType
, whereLeft err
represents the possible parse failure. -
servant-client Added a function to create Client.Request in ClientEnv #1213 #1255
The new member
makeClientRequest
ofClientEnv
is used to createhttp-client
Request
fromservant-client-core
Request
. This functionality can be used for example to set dynamic timeouts for each request.
Other changes
-
servant-client servant-client-core servant-http-streams Fix Verb with headers checking content type differently #1200 #1204
For
Verb
s with responseHeaders
, the implementation didn’t check for the content-type of the response. Now it does. -
servant-client servant-http-streams
HasClient
instance forStream
withHeaders
#1170 #1197 -
servant-client Redact the authorization header in Show and exceptions #1238
0.16.0.1
- Allow
base-compat-0.11
0.16
-
Rename
ServantError
toClientError
,ServantErr
toServerError
#1131 -
servant-client-core Rearrange modules. No more
Internal
modules, whole API is versioned. #1130 -
servant-client-core
RequestBody
is now= RequestBodyLBS LBS.ByteString | RequestBodyBS BS.ByteString | RequestBodySource (SourceIO LBS.ByteString)
i.e. no more replicates
http-client
s API. #1117 -
servant-client-core Keep structured exceptions in
ConnectionError
constructor ofClientError
#1115-| ConnectionError Text +| ConnectionError SomeException
-
servant-client-core Preserve failing request in
FailureResponse
constructor ofClientError
#1114-FailureResponse Response +-- | The server returned an error response including the +-- failing request. 'requestPath' includes the 'BaseUrl' and the +-- path of the request. +FailureResponse (RequestF () (BaseUrl, BS.ByteString)) Response
-
servant-client Fix (implement)
StreamBody
instance #1110 -
servant-client Update CookieJar with intermediate request/responses (redirects) #1104
0.15
-
Streaming refactoring. #991 #1076 #1077
The streaming functionality (
Servant.API.Stream
) is refactored to useservant
’s ownSourceIO
type (seeServant.Types.SourceT
documentation), which replaces bothStreamGenerator
andResultStream
types.New conversion type-classes are
ToSourceIO
andFromSourceIO
(replacingToStreamGenerator
andBuildFromStream
). There are instances for conduit, pipes and machines in new packages: servant-conduit servant-pipes and servant-machines respectively.Writing new framing strategies is simpler. Check existing strategies for examples.
This change shouldn’t affect you, if you don’t use streaming endpoints.
-
servant-client Separate streaming client. #1066
We now have two
http-client
based clients, inServant.Client
andServant.Client.Streaming
.Their API is the same, except for
Servant.Client
cannot requestStream
endpoints.Servant.Client
is run by directrunClientM :: ClientM a -> ClientEnv -> IO (Either ServantError a)
Servant.Client.Streaming
can requestStream
endpoints.Servant.Client.Streaming
is used by CPSisedwithClientM :: ClientM a -> ClientEnv -> (Either ServantError a -> IO b) -> IO b
To access
Stream
endpoints useServant.Client.Streaming
withwithClientM
; otherwise you can continue usingServant.Client
withrunClientM
. You can use both too,ClientEnv
andBaseUrl
types are same for both.Note:
Servant.Client.Streaming
doesn’t stream non-Stream
endpoints. Requesting ordinaryVerb
endpoints (e.g.Get
) will block until the whole response is received.There is
Servant.Client.Streaming.runClientM
function, but it has restricted type.NFData a
constraint prevents using it withSourceT
,Conduit
etc. response types.runClientM :: NFData a => ClientM a -> ClientEnv -> IO (Either ServantError a)
This change shouldn’t affect you, if you don’t use streaming endpoints.
-
servant-client-core Add
NFData (GenResponse a)
andNFData ServantError
instances. #1076
servant-client-core Add aeson
and Lift BaseUrl
instances
#1037
0.14
-
Stream
takes a status code argument-Stream method framing ctype a +Stream method status framing ctype a
-
ToStreamGenerator
definition changed, so it’s possible to write an instance for conduits.-class ToStreamGenerator f a where - toStreamGenerator :: f a -> StreamGenerator a +class ToStreamGenerator a b | a -> b where + toStreamGenerator :: a -> StreamGenerator b
(#959)
-
Added
NoFraming
streaming strategy (#959) -
servant-client-core Add
hoistClient
toHasClient
. Just likehoistServer
allows us to change the monad in which request handlers of a web application live, we also havehoistClient
for changing the monad in which client functions live. Read tutorial section for more information. (#936) -
servant-client Add more constructors to
RequestBody
, includingRequestBodyStream
. Note: we are looking for http-library agnostic API, so the might change again soon. Tell us which constructors are useful for you! (#913)
0.13.0.1
- Support
base-compat-0.10
0.13
- Streaming endpoint support. (#836)
- servant Add
Servant.API.Modifiers
(#873) - servant-client Support
http-client
’sCookieJar
(#897 #883)
0.12.0.1
- Send
Accept
header. (#858)
0.12
- Factored out into
servant-client-core
all the functionality that was independent of thehttp-client
backend.
0.11
Other changes
- Path components are escaped (#696)
Req
reqPath
field changed fromString
toBS.Builder
(#696)- Include
Req
in failure errors (#740)
0.10
Breaking changes
There shouldn’t be breaking changes. Released as a part of servant
suite.
Other changes
-
Add MonadBase and MonadBaseControl instances for ClientM (#663)
-
client asks for any content-type in Accept contentTypes non-empty list (#615)
-
Add
ClientLike
class that matches client functions generated usingclient
with client data structure. (#640) -
Allow direct use of ‘RequestBody’ (#661)
0.9.1.1
- Add MonadThrow and MonadCatch instances for ClientM
0.9
- BACKWARDS INCOMPATIBLE:
client
now returns a ClientM which is a Reader for BasicEnv. BasicEnv comprises the HttpManager and BaseUrl that have had to be passed to each method returned byclient
.
0.7.1
- Support GHC 8.0
ServantError
has anEq
instance now.
0.6
client
no longer takesBaseUrl
andManager
arguments. Instead, each function returned byclient
requires these two arguments.
0.5
- Use the
text
package instead ofString
. - Support for the
HttpVersion
,IsSecure
,RemoteHost
andVault
combinators - Added support for
path
onBaseUrl
. client
now takes an explicitManager
argument.- Use
http-api-data
instead ofServant.Common.Text
- Client functions now consider any 2xx successful.
- Remove matrix params.
- Added support for Basic authentication
- Add generalized authentication support via the
AuthClientData
type family andAuthenticateReq
data type
0.4.1
- The
HasClient
instance forDelete cts ()
now does not care at all about content types provided.
0.4
Delete
now is likeGet
,Post
,Put
, andPatch
and returns a response body- Support content-type aware combinators and
Accept
/Content-type
headers - Added a lot of tests
- Support multiple concurrent threads
- Use
ServantError
to report Errors instead ofString
- Make the clients for
Raw
endpoints return the wholeResponse
value (to be able to access response headers for example) - Support for PATCH
- Make () instances expect No Content status code, and not try to decode body.
- Add support for response headers
0.2.2
- Add TLS support
- Add matrix parameter support