git.iko.soy/servant
on master help sign in
update examples in servant-client. fixes #75
ff6c04cAlp Mestanogullari
servant-client/README.md+6−5
compare with master
unifiedsplit
@@ -7,14 +7,15 @@ This library lets you automatically derive Haskell functions that let you query
7## Example
7## Example
8
8
9``` haskell
9``` haskell
10−type MyApi = "books" :> Get [Book] -- GET /books
10+type MyApi = "books" :> Get '[JSON] [Book] -- GET /books
11− :<|> "books" :> ReqBody Book :> Post Book -- POST /books
11+ :<|> "books" :> ReqBody Book :> Post '[JSON] Book -- POST /books
12
12
13myApi :: Proxy MyApi
13myApi :: Proxy MyApi
14myApi = Proxy
14myApi = Proxy
15
15
16−getAllBooks :: BaseUrl -> EitherT String IO [Book]
16+getAllBooks :: EitherT String IO [Book]
17−postNewBook :: Book -> BaseUrl -> EitherT String IO Book
17+postNewBook :: Book -> EitherT String IO Book
18-- 'client' allows you to produce operations to query an API from a client.
18-- 'client' allows you to produce operations to query an API from a client.
19−(getAllBooks :<|> postNewBook) = client myApi
19+(getAllBooks :<|> postNewBook) = client myApi host
20+ where host = BaseUrl Http "localhost" 8080
20```
21```
servant-client/src/Servant/Client.hs+51−40
@@ -43,15 +43,16 @@ import Servant.Common.Req
43
43
44-- | 'client' allows you to produce operations to query an API from a client.
44-- | 'client' allows you to produce operations to query an API from a client.
45--
45--
46−-- > type MyApi = "books" :> Get [Book] -- GET /books
46+-- > type MyApi = "books" :> Get '[JSON] [Book] -- GET /books
47−-- > :<|> "books" :> ReqBody Book :> Post Book -- POST /books
47+-- > :<|> "books" :> ReqBody '[JSON] Book :> Post Book -- POST /books
48-- >
48-- >
49-- > myApi :: Proxy MyApi
49-- > myApi :: Proxy MyApi
50-- > myApi = Proxy
50-- > myApi = Proxy
51-- >
51-- >
52−-- > getAllBooks :: BaseUrl -> EitherT String IO [Book]
52+-- > getAllBooks :: EitherT String IO [Book]
53−-- > postNewBook :: Book -> BaseUrl -> EitherT String IO Book
53+-- > postNewBook :: Book -> EitherT String IO Book
54−-- > (getAllBooks :<|> postNewBook) = client myApi
54+-- > (getAllBooks :<|> postNewBook) = client myApi host
55+-- > where host = BaseUrl Http "localhost" 8080
55client :: HasClient layout => Proxy layout -> BaseUrl -> Client layout
56client :: HasClient layout => Proxy layout -> BaseUrl -> Client layout
56client p baseurl = clientWithRoute p defReq baseurl
57client p baseurl = clientWithRoute p defReq baseurl
57
58
@@ -68,15 +69,16 @@ class HasClient layout where
68-- one function for querying @a@ and another one for querying @b@,
69-- one function for querying @a@ and another one for querying @b@,
69-- stitching them together with ':<|>', which really is just like a pair.
70-- stitching them together with ':<|>', which really is just like a pair.
70--
71--
71−-- > type MyApi = "books" :> Get [Book] -- GET /books
72+-- > type MyApi = "books" :> Get '[JSON] [Book] -- GET /books
72−-- > :<|> "books" :> ReqBody Book :> Post Book -- POST /books
73+-- > :<|> "books" :> ReqBody '[JSON] Book :> Post Book -- POST /books
73-- >
74-- >
74-- > myApi :: Proxy MyApi
75-- > myApi :: Proxy MyApi
75-- > myApi = Proxy
76-- > myApi = Proxy
76-- >
77-- >
77−-- > getAllBooks :: BaseUrl -> EitherT String IO [Book]
78+-- > getAllBooks :: EitherT String IO [Book]
78−-- > postNewBook :: Book -> BaseUrl -> EitherT String IO Book
79+-- > postNewBook :: Book -> EitherT String IO Book
79−-- > (getAllBooks :<|> postNewBook) = client myApi
80+-- > (getAllBooks :<|> postNewBook) = client myApi host
81+-- > where host = BaseUrl Http "localhost" 8080
80instance (HasClient a, HasClient b) => HasClient (a :<|> b) where
82instance (HasClient a, HasClient b) => HasClient (a :<|> b) where
81 type Client (a :<|> b) = Client a :<|> Client b
83 type Client (a :<|> b) = Client a :<|> Client b
82 clientWithRoute Proxy req baseurl =
84 clientWithRoute Proxy req baseurl =
@@ -94,13 +96,14 @@ instance (HasClient a, HasClient b) => HasClient (a :<|> b) where
94--
96--
95-- Example:
97-- Example:
96--
98--
97−-- > type MyApi = "books" :> Capture "isbn" Text :> Get Book
99+-- > type MyApi = "books" :> Capture "isbn" Text :> Get '[JSON] Book
98-- >
100-- >
99-- > myApi :: Proxy MyApi
101-- > myApi :: Proxy MyApi
100-- > myApi = Proxy
102-- > myApi = Proxy
101-- >
103-- >
102−-- > getBook :: Text -> BaseUrl -> EitherT String IO Book
104+-- > getBook :: Text -> EitherT String IO Book
103−-- > getBook = client myApi
105+-- > getBook = client myApi host
106+-- > where host = BaseUrl Http "localhost" 8080
104-- > -- then you can just use "getBook" to query that endpoint
107-- > -- then you can just use "getBook" to query that endpoint
105instance (KnownSymbol capture, ToText a, HasClient sublayout)
108instance (KnownSymbol capture, ToText a, HasClient sublayout)
106 => HasClient (Capture capture a :> sublayout) where
109 => HasClient (Capture capture a :> sublayout) where
@@ -205,19 +208,20 @@ instance
205--
208--
206-- Example:
209-- Example:
207--
210--
208−-- > newtype Referer = Referer Text
211+-- > newtype Referer = Referer { referrer :: Text }
209−-- > deriving (Eq, Show, FromText, ToText)
212+-- > deriving (Eq, Show, Generic, FromText, ToText)
210-- >
213-- >
211-- > -- GET /view-my-referer
214-- > -- GET /view-my-referer
212−-- > type MyApi = "view-my-referer" :> Header "Referer" Referer :> Get Referer
215+-- > type MyApi = "view-my-referer" :> Header "Referer" Referer :> Get '[JSON] Referer
213-- >
216-- >
214-- > myApi :: Proxy MyApi
217-- > myApi :: Proxy MyApi
215-- > myApi = Proxy
218-- > myApi = Proxy
216-- >
219-- >
217−-- > viewReferer :: Maybe Referer -> BaseUrl -> EitherT String IO Book
220+-- > viewReferer :: Maybe Referer -> EitherT String IO Book
218−-- > viewReferer = client myApi
221+-- > viewReferer = client myApi host
222+-- > where host = BaseUrl Http "localhost" 8080
219-- > -- then you can just use "viewRefer" to query that endpoint
223-- > -- then you can just use "viewRefer" to query that endpoint
220−-- > -- specifying Nothing or Just "http://haskell.org/" as arguments
224+-- > -- specifying Nothing or e.g Just "http://haskell.org/" as arguments
221instance (KnownSymbol sym, ToText a, HasClient sublayout)
225instance (KnownSymbol sym, ToText a, HasClient sublayout)
222 => HasClient (Header sym a :> sublayout) where
226 => HasClient (Header sym a :> sublayout) where
223
227
@@ -366,13 +370,14 @@ instance
366--
370--
367-- Example:
371-- Example:
368--
372--
369−-- > type MyApi = "books" :> QueryParam "author" Text :> Get [Book]
373+-- > type MyApi = "books" :> QueryParam "author" Text :> Get '[JSON] [Book]
370-- >
374-- >
371-- > myApi :: Proxy MyApi
375-- > myApi :: Proxy MyApi
372-- > myApi = Proxy
376-- > myApi = Proxy
373-- >
377-- >
374−-- > getBooksBy :: Maybe Text -> BaseUrl -> EitherT String IO [Book]
378+-- > getBooksBy :: Maybe Text -> EitherT String IO [Book]
375−-- > getBooksBy = client myApi
379+-- > getBooksBy = client myApi host
380+-- > where host = BaseUrl Http "localhost" 8080
376-- > -- then you can just use "getBooksBy" to query that endpoint.
381-- > -- then you can just use "getBooksBy" to query that endpoint.
377-- > -- 'getBooksBy Nothing' for all books
382-- > -- 'getBooksBy Nothing' for all books
378-- > -- 'getBooksBy (Just "Isaac Asimov")' to get all books by Isaac Asimov
383-- > -- 'getBooksBy (Just "Isaac Asimov")' to get all books by Isaac Asimov
@@ -411,13 +416,14 @@ instance (KnownSymbol sym, ToText a, HasClient sublayout)
411--
416--
412-- Example:
417-- Example:
413--
418--
414−-- > type MyApi = "books" :> QueryParams "authors" Text :> Get [Book]
419+-- > type MyApi = "books" :> QueryParams "authors" Text :> Get '[JSON] [Book]
415-- >
420-- >
416-- > myApi :: Proxy MyApi
421-- > myApi :: Proxy MyApi
417-- > myApi = Proxy
422-- > myApi = Proxy
418-- >
423-- >
419−-- > getBooksBy :: [Text] -> BaseUrl -> EitherT String IO [Book]
424+-- > getBooksBy :: [Text] -> EitherT String IO [Book]
420−-- > getBooksBy = client myApi
425+-- > getBooksBy = client myApi host
426+-- > where host = BaseUrl Http "localhost" 8080
421-- > -- then you can just use "getBooksBy" to query that endpoint.
427-- > -- then you can just use "getBooksBy" to query that endpoint.
422-- > -- 'getBooksBy []' for all books
428-- > -- 'getBooksBy []' for all books
423-- > -- 'getBooksBy ["Isaac Asimov", "Robert A. Heinlein"]'
429-- > -- 'getBooksBy ["Isaac Asimov", "Robert A. Heinlein"]'
@@ -451,13 +457,14 @@ instance (KnownSymbol sym, ToText a, HasClient sublayout)
451--
457--
452-- Example:
458-- Example:
453--
459--
454−-- > type MyApi = "books" :> QueryFlag "published" :> Get [Book]
460+-- > type MyApi = "books" :> QueryFlag "published" :> Get '[JSON] [Book]
455-- >
461-- >
456-- > myApi :: Proxy MyApi
462-- > myApi :: Proxy MyApi
457-- > myApi = Proxy
463-- > myApi = Proxy
458-- >
464-- >
459−-- > getBooks :: Bool -> BaseUrl -> EitherT String IO [Book]
465+-- > getBooks :: Bool -> EitherT String IO [Book]
460−-- > getBooks = client myApi
466+-- > getBooks = client myApi host
467+-- > where host = BaseUrl Http "localhost" 8080
461-- > -- then you can just use "getBooks" to query that endpoint.
468-- > -- then you can just use "getBooks" to query that endpoint.
462-- > -- 'getBooksBy False' for all books
469-- > -- 'getBooksBy False' for all books
463-- > -- 'getBooksBy True' to only get _already published_ books
470-- > -- 'getBooksBy True' to only get _already published_ books
@@ -492,13 +499,14 @@ instance (KnownSymbol sym, HasClient sublayout)
492--
499--
493-- Example:
500-- Example:
494--
501--
495−-- > type MyApi = "books" :> MatrixParam "author" Text :> Get [Book]
502+-- > type MyApi = "books" :> MatrixParam "author" Text :> Get '[JSON] [Book]
496-- >
503-- >
497-- > myApi :: Proxy MyApi
504-- > myApi :: Proxy MyApi
498-- > myApi = Proxy
505-- > myApi = Proxy
499-- >
506-- >
500−-- > getBooksBy :: Maybe Text -> BaseUrl -> EitherT String IO [Book]
507+-- > getBooksBy :: Maybe Text -> EitherT String IO [Book]
501−-- > getBooksBy = client myApi
508+-- > getBooksBy = client myApi host
509+-- > where host = BaseUrl Http "localhost" 8080
502-- > -- then you can just use "getBooksBy" to query that endpoint.
510-- > -- then you can just use "getBooksBy" to query that endpoint.
503-- > -- 'getBooksBy Nothing' for all books
511-- > -- 'getBooksBy Nothing' for all books
504-- > -- 'getBooksBy (Just "Isaac Asimov")' to get all books by Isaac Asimov
512-- > -- 'getBooksBy (Just "Isaac Asimov")' to get all books by Isaac Asimov
@@ -536,13 +544,14 @@ instance (KnownSymbol sym, ToText a, HasClient sublayout)
536--
544--
537-- Example:
545-- Example:
538--
546--
539−-- > type MyApi = "books" :> MatrixParams "authors" Text :> Get [Book]
547+-- > type MyApi = "books" :> MatrixParams "authors" Text :> Get '[JSON] [Book]
540-- >
548-- >
541-- > myApi :: Proxy MyApi
549-- > myApi :: Proxy MyApi
542-- > myApi = Proxy
550-- > myApi = Proxy
543-- >
551-- >
544−-- > getBooksBy :: [Text] -> BaseUrl -> EitherT String IO [Book]
552+-- > getBooksBy :: [Text] -> EitherT String IO [Book]
545−-- > getBooksBy = client myApi
553+-- > getBooksBy = client myApi host
554+-- > where host = BaseUrl Http "localhost" 8080
546-- > -- then you can just use "getBooksBy" to query that endpoint.
555-- > -- then you can just use "getBooksBy" to query that endpoint.
547-- > -- 'getBooksBy []' for all books
556-- > -- 'getBooksBy []' for all books
548-- > -- 'getBooksBy ["Isaac Asimov", "Robert A. Heinlein"]'
557-- > -- 'getBooksBy ["Isaac Asimov", "Robert A. Heinlein"]'
@@ -576,13 +585,14 @@ instance (KnownSymbol sym, ToText a, HasClient sublayout)
576--
585--
577-- Example:
586-- Example:
578--
587--
579−-- > type MyApi = "books" :> MatrixFlag "published" :> Get [Book]
588+-- > type MyApi = "books" :> MatrixFlag "published" :> Get '[JSON] [Book]
580-- >
589-- >
581-- > myApi :: Proxy MyApi
590-- > myApi :: Proxy MyApi
582-- > myApi = Proxy
591-- > myApi = Proxy
583-- >
592-- >
584−-- > getBooks :: Bool -> BaseUrl -> EitherT String IO [Book]
593+-- > getBooks :: Bool -> EitherT String IO [Book]
585−-- > getBooks = client myApi
594+-- > getBooks = client myApi host
595+-- > where host = BaseUrl Http "localhost" 8080
586-- > -- then you can just use "getBooks" to query that endpoint.
596-- > -- then you can just use "getBooks" to query that endpoint.
587-- > -- 'getBooksBy False' for all books
597-- > -- 'getBooksBy False' for all books
588-- > -- 'getBooksBy True' to only get _already published_ books
598-- > -- 'getBooksBy True' to only get _already published_ books
@@ -621,13 +631,14 @@ instance HasClient Raw where
621--
631--
622-- Example:
632-- Example:
623--
633--
624−-- > type MyApi = "books" :> ReqBody Book :> Post Book
634+-- > type MyApi = "books" :> ReqBody '[JSON] Book :> Post '[JSON] Book
625-- >
635-- >
626-- > myApi :: Proxy MyApi
636-- > myApi :: Proxy MyApi
627-- > myApi = Proxy
637-- > myApi = Proxy
628-- >
638-- >
629−-- > addBook :: Book -> BaseUrl -> EitherT String IO Book
639+-- > addBook :: Book -> EitherT String IO Book
630−-- > addBook = client myApi
640+-- > addBook = client myApi host
641+-- > where host = BaseUrl Http "localhost" 8080
631-- > -- then you can just use "addBook" to query that endpoint
642-- > -- then you can just use "addBook" to query that endpoint
632instance (MimeRender ct a, HasClient sublayout)
643instance (MimeRender ct a, HasClient sublayout)
633 => HasClient (ReqBody (ct ': cts) a :> sublayout) where
644 => HasClient (ReqBody (ct ': cts) a :> sublayout) where