Servant.Links

Type safe generation of internal links.

Given an API with a few endpoints:

>>> :set -XDataKinds -XTypeFamilies -XTypeOperators
>>> import Servant.API
>>> import Servant.Links
>>> import Data.Proxy
>>> 
>>> type Hello = "hello" :> Get '[JSON] Int
>>> type Bye   = "bye"   :> QueryParam "name" String :> Delete '[JSON] NoContent
>>> type API   = Hello :<|> Bye
>>> let api = Proxy :: Proxy API

It is possible to generate links that are guaranteed to be within API with safeLink. The first argument to safeLink is a type representing the API you would like to restrict links to. The second argument is the destination endpoint you would like the link to point to, this will need to end with a verb like GET or POST. Further arguments may be required depending on the type of the endpoint. If everything lines up you will get a Link out the other end.

You may omit QueryParams and the like should you not want to provide them, but types which form part of the URL path like Capture must be included. The reason you may want to omit QueryParams is that safeLink is a bit magical: if parameters are included that could take input it will return a function that accepts that input and generates a link. This is best shown with an example. Here, a link is generated with no parameters:

>>> let hello = Proxy :: Proxy ("hello" :> Get '[JSON] Int)
>>> toUrlPiece (safeLink api hello :: Link)
"hello"

If the API has an endpoint with parameters then we can generate links with or without those:

>>> let with = Proxy :: Proxy ("bye" :> QueryParam "name" String :> Delete '[JSON] NoContent)
>>> toUrlPiece $ safeLink api with (Just "Hubert")
"bye?name=Hubert"

>>> let without = Proxy :: Proxy ("bye" :> Delete '[JSON] NoContent)
>>> toUrlPiece $ safeLink api without
"bye"

If you would like create a helper for generating links only within that API, you can partially apply safeLink if you specify a correct type signature like so:

>>> :set -XConstraintKinds
>>> :{
>>> let apiLink :: (IsElem endpoint API, HasLink endpoint)
>>> => Proxy endpoint -> MkLink endpoint Link
>>> apiLink = safeLink api
>>> :}

safeLink' allows to make specialise the output:

>>> safeLink' toUrlPiece api without
"bye"

>>> :{
>>> let apiTextLink :: (IsElem endpoint API, HasLink endpoint)
>>> => Proxy endpoint -> MkLink endpoint Text
>>> apiTextLink = safeLink' toUrlPiece api
>>> :}

>>> apiTextLink without
"bye"

Attempting to construct a link to an endpoint that does not exist in api will result in a type error like this:

>>> let bad_link = Proxy :: Proxy ("hello" :> Delete '[JSON] NoContent)
>>> safeLink api bad_link
...
...Could not deduce...
...

This error is essentially saying that the type family couldn't find bad_link under api after trying the open (but empty) type family IsElem' as a last resort.

Since: servant-0.14.1

Documentation

module Servant.API.TypeLevel

Building and using safe links

Note that URI is from the Network.URI module in the network-uri package.

safeLink

Arguments

:: (IsElem endpoint api, HasLink endpoint)

=> Proxy api

The whole API that this endpoint is a part of

-> Proxy endpoint

The API endpoint you would like to point to

-> MkLink endpoint Link

Create a valid (by construction) relative URI with query params.

This function will only typecheck if endpoint is part of the API api

safeLink'

Arguments

:: (IsElem endpoint api, HasLink endpoint)

=> (Link -> a)

-> Proxy api

The whole API that this endpoint is a part of

-> Proxy endpoint

The API endpoint you would like to point to

-> MkLink endpoint a

More general safeLink.

allLinks :: forall api. HasLink api => Proxy api -> MkLink api Link

Create all links in an API.

Note that the api type must be restricted to the endpoints that have valid links to them.

>>> type API = "foo" :> Capture "name" Text :> Get '[JSON] Text :<|> "bar" :> Capture "name" Int :> Get '[JSON] Double
>>> let fooLink :<|> barLink = allLinks (Proxy :: Proxy API)
>>> :t fooLink
fooLink :: Text -> Link
>>> :t barLink
barLink :: Int -> Link

Note: nested APIs don't work well with this approach

>>> :kind! MkLink (Capture "nest" Char :> (Capture "x" Int :> Get '[JSON] Int :<|> Capture "y" Double :> Get '[JSON] Double)) Link
MkLink (Capture "nest" Char :> (Capture "x" Int :> Get '[JSON] Int :<|> Capture "y" Double :> Get '[JSON] Double)) Link :: *
= Char -> (Int -> Link) :<|> (Double -> Link)

allLinks' :: forall api a. HasLink api => (Link -> a) -> Proxy api -> MkLink api a

More general allLinks. See safeLink'.

data URI

Represents a general universal resource identifier using its component parts.

For example, for the URI

  foo://[e-mail]:42/ghc?query#frag

the components are:

Constructors

URI

Fields

• uriScheme :: String

  foo:

• uriAuthority :: Maybe URIAuth

  //[e-mail]:42

• uriPath :: String

  /ghc

• uriQuery :: String

  ?query

• uriFragment :: String

  #frag

Instances

Eq URI

Defined in Network.URI

Methods

(==) :: URI -> URI -> Bool

(/=) :: URI -> URI -> Bool

Data URI

Defined in Network.URI

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> URI -> c URI

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c URI

toConstr :: URI -> Constr

dataTypeOf :: URI -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c URI)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c URI)

gmapT :: (forall b. Data b => b -> b) -> URI -> URI

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> URI -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> URI -> r

gmapQ :: (forall d. Data d => d -> u) -> URI -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> URI -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> URI -> m URI

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> URI -> m URI

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> URI -> m URI

Ord URI

Defined in Network.URI

Methods

compare :: URI -> URI -> Ordering

(<) :: URI -> URI -> Bool

(<=) :: URI -> URI -> Bool

(>) :: URI -> URI -> Bool

(>=) :: URI -> URI -> Bool

max :: URI -> URI -> URI

min :: URI -> URI -> URI

Show URI

Defined in Network.URI

Methods

showsPrec :: Int -> URI -> ShowS

show :: URI -> String

showList :: [URI] -> ShowS

Generic URI

Defined in Network.URI

Associated Types

type Rep URI :: * -> *

Methods

from :: URI -> Rep URI x

to :: Rep URI x -> URI

NFData URI

Defined in Network.URI

Methods

rnf :: URI -> ()

type Rep URI

Defined in Network.URI

type Rep URI = D1 (MetaData "URI" "Network.URI" "network-uri-2.6.1.0-AstEwZoXrlUJQq4VkxaVo9" False) (C1 (MetaCons "URI" PrefixI True) ((S1 (MetaSel (Just "uriScheme") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Just "uriAuthority") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe URIAuth))) :*: (S1 (MetaSel (Just "uriPath") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: (S1 (MetaSel (Just "uriQuery") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Just "uriFragment") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String)))))

Generics

data AsLink (a :: *)

A type that specifies that an API record contains a set of links.

Since: servant-0.14.1

Instances

GenericMode (AsLink a)

Defined in Servant.Links

Associated Types

type (AsLink a) :- api :: *

type (AsLink a) :- api

Defined in Servant.Links

type (AsLink a) :- api = MkLink api a

fieldLink :: (IsElem endpoint (ToServantApi routes), HasLink endpoint, GenericServant routes AsApi) => (routes AsApi -> endpoint) -> MkLink endpoint Link

Given an API record field, create a link for that route. Only the field's type is used.

data Record route = Record
    { _get :: route :- Capture "id" Int :> Get '[JSON] String
    , _put :: route :- ReqBody '[JSON] Int :> Put '[JSON] Bool
    }
  deriving (Generic)

getLink :: Int -> Link
getLink = fieldLink _get

Since: servant-0.14.1

fieldLink' :: forall routes endpoint a. (IsElem endpoint (ToServantApi routes), HasLink endpoint, GenericServant routes AsApi) => (Link -> a) -> (routes AsApi -> endpoint) -> MkLink endpoint a

More general version of fieldLink

Since: servant-0.14.1

allFieldLinks :: (HasLink (ToServantApi routes), GenericServant routes (AsLink Link), ToServant routes (AsLink Link) ~ MkLink (ToServantApi routes) Link) => routes (AsLink Link)

Get all links as a record.

Since: servant-0.14.1

allFieldLinks' :: forall routes a. (HasLink (ToServantApi routes), GenericServant routes (AsLink a), ToServant routes (AsLink a) ~ MkLink (ToServantApi routes) a) => (Link -> a) -> routes (AsLink a)

More general version of allFieldLinks.

Since: servant-0.14.1

Adding custom types

class HasLink endpoint where

Construct a toLink for an endpoint.

Minimal complete definition

toLink

Associated Types

type MkLink endpoint (a :: *)

Methods

toLink

Arguments

:: (Link -> a)

-> Proxy endpoint

The API endpoint you would like to point to

-> Link

-> MkLink endpoint a

Instances

HasLink EmptyAPI

Defined in Servant.Links

Associated Types

type MkLink EmptyAPI a :: *

Methods

toLink :: (Link -> a) -> Proxy EmptyAPI -> Link -> MkLink EmptyAPI a

HasLink Raw

Defined in Servant.Links

Associated Types

type MkLink Raw a :: *

Methods

toLink :: (Link -> a) -> Proxy Raw -> Link -> MkLink Raw a

(HasLink a, HasLink b) => HasLink (a :<|> b :: *)

Defined in Servant.Links

Associated Types

type MkLink (a :<|> b) a :: *

Methods

toLink :: (Link -> a0) -> Proxy (a :<|> b) -> Link -> MkLink (a :<|> b) a0

HasLink sub => HasLink (HttpVersion :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (HttpVersion :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (HttpVersion :> sub) -> Link -> MkLink (HttpVersion :> sub) a

HasLink sub => HasLink (Vault :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (Vault :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (Vault :> sub) -> Link -> MkLink (Vault :> sub) a

HasLink sub => HasLink (BasicAuth realm a :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (BasicAuth realm a :> sub) a :: *

Methods

toLink :: (Link -> a0) -> Proxy (BasicAuth realm a :> sub) -> Link -> MkLink (BasicAuth realm a :> sub) a0

(ToHttpApiData v, HasLink sub) => HasLink (CaptureAll sym v :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (CaptureAll sym v :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (CaptureAll sym v :> sub) -> Link -> MkLink (CaptureAll sym v :> sub) a

(ToHttpApiData v, HasLink sub) => HasLink (Capture' mods sym v :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (Capture' mods sym v :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (Capture' mods sym v :> sub) -> Link -> MkLink (Capture' mods sym v :> sub) a

HasLink sub => HasLink (Description s :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (Description s :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (Description s :> sub) -> Link -> MkLink (Description s :> sub) a

HasLink sub => HasLink (Summary s :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (Summary s :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (Summary s :> sub) -> Link -> MkLink (Summary s :> sub) a

HasLink sub => HasLink (AuthProtect tag :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (AuthProtect tag :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (AuthProtect tag :> sub) -> Link -> MkLink (AuthProtect tag :> sub) a

HasLink sub => HasLink (IsSecure :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (IsSecure :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (IsSecure :> sub) -> Link -> MkLink (IsSecure :> sub) a

HasLink sub => HasLink (Header' mods sym a :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (Header' mods sym a :> sub) a :: *

Methods

toLink :: (Link -> a0) -> Proxy (Header' mods sym a :> sub) -> Link -> MkLink (Header' mods sym a :> sub) a0

(KnownSymbol sym, HasLink sub) => HasLink (QueryFlag sym :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (QueryFlag sym :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (QueryFlag sym :> sub) -> Link -> MkLink (QueryFlag sym :> sub) a

(KnownSymbol sym, ToHttpApiData v, HasLink sub) => HasLink (QueryParams sym v :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (QueryParams sym v :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (QueryParams sym v :> sub) -> Link -> MkLink (QueryParams sym v :> sub) a

(KnownSymbol sym, ToHttpApiData v, HasLink sub, SBoolI (FoldRequired mods)) => HasLink (QueryParam' mods sym v :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (QueryParam' mods sym v :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (QueryParam' mods sym v :> sub) -> Link -> MkLink (QueryParam' mods sym v :> sub) a

HasLink sub => HasLink (RemoteHost :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (RemoteHost :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (RemoteHost :> sub) -> Link -> MkLink (RemoteHost :> sub) a

HasLink sub => HasLink (ReqBody' mods ct a :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (ReqBody' mods ct a :> sub) a :: *

Methods

toLink :: (Link -> a0) -> Proxy (ReqBody' mods ct a :> sub) -> Link -> MkLink (ReqBody' mods ct a :> sub) a0

(KnownSymbol sym, HasLink sub) => HasLink (sym :> sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (sym :> sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (sym :> sub) -> Link -> MkLink (sym :> sub) a

HasLink sub => HasLink (WithNamedContext name context sub :: *)

Defined in Servant.Links

Associated Types

type MkLink (WithNamedContext name context sub) a :: *

Methods

toLink :: (Link -> a) -> Proxy (WithNamedContext name context sub) -> Link -> MkLink (WithNamedContext name context sub) a

HasLink (Verb m s ct a :: *)

Defined in Servant.Links

Associated Types

type MkLink (Verb m s ct a) a :: *

Methods

toLink :: (Link -> a0) -> Proxy (Verb m s ct a) -> Link -> MkLink (Verb m s ct a) a0

HasLink (Stream m status fr ct a :: *)

Defined in Servant.Links

Associated Types

type MkLink (Stream m status fr ct a) a :: *

Methods

toLink :: (Link -> a0) -> Proxy (Stream m status fr ct a) -> Link -> MkLink (Stream m status fr ct a) a0

data Link

A safe link datatype. The only way of constructing a Link is using safeLink, which means any Link is guaranteed to be part of the mentioned API.

Instances

Show Link

Defined in Servant.Links

Methods

showsPrec :: Int -> Link -> ShowS

show :: Link -> String

showList :: [Link] -> ShowS

ToHttpApiData Link

Defined in Servant.Links

Methods

toUrlPiece :: Link -> Text

toEncodedUrlPiece :: Link -> Builder

toHeader :: Link -> ByteString

toQueryParam :: Link -> Text

linkURI :: Link -> URI

Transform Link into URI.

>>> type API = "something" :> Get '[JSON] Int
>>> linkURI $ safeLink (Proxy :: Proxy API) (Proxy :: Proxy API)
something

>>> type API = "sum" :> QueryParams "x" Int :> Get '[JSON] Int
>>> linkURI $ safeLink (Proxy :: Proxy API) (Proxy :: Proxy API) [1, 2, 3]
sum?x[]=1&x[]=2&x[]=3

>>> type API = "foo/bar" :> Get '[JSON] Int
>>> linkURI $ safeLink (Proxy :: Proxy API) (Proxy :: Proxy API)
foo%2Fbar

>>> type SomeRoute = "abc" :> Capture "email" String :> Put '[JSON] ()
>>> let someRoute = Proxy :: Proxy SomeRoute
>>> safeLink someRoute someRoute "[e-mail]"
Link {_segments = ["abc","test%40example.com"], _queryParams = []}

>>> linkURI $ safeLink someRoute someRoute "[e-mail]"
abc/test%40example.com

linkURI' :: LinkArrayElementStyle -> Link -> URI

Configurable linkURI.

>>> type API = "sum" :> QueryParams "x" Int :> Get '[JSON] Int
>>> linkURI' LinkArrayElementBracket $ safeLink (Proxy :: Proxy API) (Proxy :: Proxy API) [1, 2, 3]
sum?x[]=1&x[]=2&x[]=3

>>> linkURI' LinkArrayElementPlain $ safeLink (Proxy :: Proxy API) (Proxy :: Proxy API) [1, 2, 3]
sum?x=1&x=2&x=3

data LinkArrayElementStyle

How to encode array query elements.

Constructors

LinkArrayElementBracket

foo[]=1&foo[]=2

LinkArrayElementPlain

foo=1&foo=2

Instances

Bounded LinkArrayElementStyle

Defined in Servant.Links

Methods

minBound :: LinkArrayElementStyle

maxBound :: LinkArrayElementStyle

Enum LinkArrayElementStyle

Defined in Servant.Links

Methods

succ :: LinkArrayElementStyle -> LinkArrayElementStyle

pred :: LinkArrayElementStyle -> LinkArrayElementStyle

toEnum :: Int -> LinkArrayElementStyle

fromEnum :: LinkArrayElementStyle -> Int

enumFrom :: LinkArrayElementStyle -> [LinkArrayElementStyle]

enumFromThen :: LinkArrayElementStyle -> LinkArrayElementStyle -> [LinkArrayElementStyle]

enumFromTo :: LinkArrayElementStyle -> LinkArrayElementStyle -> [LinkArrayElementStyle]

enumFromThenTo :: LinkArrayElementStyle -> LinkArrayElementStyle -> LinkArrayElementStyle -> [LinkArrayElementStyle]

Eq LinkArrayElementStyle

Defined in Servant.Links

Methods

(==) :: LinkArrayElementStyle -> LinkArrayElementStyle -> Bool

(/=) :: LinkArrayElementStyle -> LinkArrayElementStyle -> Bool

Ord LinkArrayElementStyle

Defined in Servant.Links

Methods

compare :: LinkArrayElementStyle -> LinkArrayElementStyle -> Ordering

(<) :: LinkArrayElementStyle -> LinkArrayElementStyle -> Bool

(<=) :: LinkArrayElementStyle -> LinkArrayElementStyle -> Bool

(>) :: LinkArrayElementStyle -> LinkArrayElementStyle -> Bool

(>=) :: LinkArrayElementStyle -> LinkArrayElementStyle -> Bool

max :: LinkArrayElementStyle -> LinkArrayElementStyle -> LinkArrayElementStyle

min :: LinkArrayElementStyle -> LinkArrayElementStyle -> LinkArrayElementStyle

Show LinkArrayElementStyle

Defined in Servant.Links

Methods

showsPrec :: Int -> LinkArrayElementStyle -> ShowS

show :: LinkArrayElementStyle -> String

showList :: [LinkArrayElementStyle] -> ShowS

Link accessors

data Param

Query parameter.

Constructors

SingleParam String Text

ArrayElemParam String Text

FlagParam String

Instances

Show Param

Defined in Servant.Links

Methods

showsPrec :: Int -> Param -> ShowS

show :: Param -> String

showList :: [Param] -> ShowS

linkSegments :: Link -> [String]

linkQueryParams :: Link -> [Param]