Safe Haskell	None
Language	Haskell2010

Servant.API.QueryParam

Synopsis

Documentation

data QueryParam sym a Source

Lookup the value associated to the sym query string parameter and try to extract it as a value of type a.

Example:

-- /books?author=<author name>
type MyApi = "books" :> QueryParam "author" Text :> Get [Book]

Instances

(KnownSymbol sym, FromText a, HasServer sublayout) => HasServer ((:>) * (QueryParam Symbol * sym a) sublayout)

If you use QueryParam "author" Text in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type Maybe Text.

This lets servant worry about looking it up in the query string and turning it into a value of the type you specify, enclosed in Maybe, because it may not be there and servant would then hand you Nothing.

You can control how it'll be converted from Text to your type by simply providing an instance of FromText for your type.

Example:

type MyApi = "books" :> QueryParam "author" Text :> Get [Book]

server :: Server MyApi
server = getBooksBy
  where getBooksBy :: Maybe Text -> EitherT (Int, String) IO [Book]
        getBooksBy Nothing       = ...return all books...
        getBooksBy (Just author) = ...return books by the given author...

type Server ((:>) * (QueryParam Symbol * sym a) sublayout) = Maybe a -> Server sublayout

data QueryParams sym a Source

Lookup the values associated to the sym query string parameter and try to extract it as a value of type [a]. This is typically meant to support query string parameters of the form param[]=val1&param[]=val2 and so on. Note that servant doesn't actually require the []s and will fetch the values just fine with param=val1&param=val2, too.

Example:

-- /books?authors[]=<author1>&authors[]=<author2>&...
type MyApi = "books" :> QueryParams "authors" Text :> Get [Book]

Instances

(KnownSymbol sym, FromText a, HasServer sublayout) => HasServer ((:>) * (QueryParams Symbol * sym a) sublayout)

If you use QueryParams "authors" Text in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type [Text].

This lets servant worry about looking up 0 or more values in the query string associated to authors and turning each of them into a value of the type you specify.

You can control how the individual values are converted from Text to your type by simply providing an instance of FromText for your type.

Example:

type MyApi = "books" :> QueryParams "authors" Text :> Get [Book]

server :: Server MyApi
server = getBooksBy
  where getBooksBy :: [Text] -> EitherT (Int, String) IO [Book]
        getBooksBy authors = ...return all books by these authors...

type Server ((:>) * (QueryParams Symbol * sym a) sublayout) = [a] -> Server sublayout

data QueryFlag sym Source

Lookup a potentially value-less query string parameter with boolean semantics. If the param sym is there without any value, or if it's there with value "true" or "1", it's interpreted as True. Otherwise, it's interpreted as False.

Example:

-- /books?published
type MyApi = "books" :> QueryFlag "published" :> Get [Book]

Instances

(KnownSymbol sym, HasServer sublayout) => HasServer ((:>) * (QueryFlag Symbol sym) sublayout)

If you use QueryFlag "published" in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type Bool.

Example:

type MyApi = "books" :> QueryFlag "published" :> Get [Book]

server :: Server MyApi
server = getBooks
  where getBooks :: Bool -> EitherT (Int, String) IO [Book]
        getBooks onlyPublished = ...return all books, or only the ones that are already published, depending on the argument...

type Server ((:>) * (QueryFlag Symbol sym) sublayout) = Bool -> Server sublayout