<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><htmlxmlns="http://www.w3.org/1999/xhtml"><head><metahttp-equiv="Content-Type"content="text/html; charset=UTF-8"/><title>Servant.Server</title><linkhref="ocean.css"rel="stylesheet"type="text/css"title="Ocean"/><scriptsrc="haddock-util.js"type="text/javascript"></script><scripttype="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Servant-Server.html");};
</script></head><body><divid="package-header"><ulclass="links"id="page-menu"><li><ahref="src/Servant-Server.html">Source</a></li><li><ahref="index.html">Contents</a></li><li><ahref="doc-index.html">Index</a></li></ul><pclass="caption">servant-0.2: A family of combinators for defining webservices APIs and serving them</p></div><divid="content"><divid="module-header"><tableclass="info"><tr><th>Safe Haskell</th><td>None</td></tr><tr><th>Language</th><td>Haskell2010</td></tr></table><pclass="caption">Servant.Server</p></div><divid="table-of-contents"><pclass="caption">Contents</p><ul><li><ahref="#g:1">Implementing Servers</a></li><li><ahref="#g:2">Route mismatch</a></li></ul></div><divid="description"><pclass="caption">Description</p><divclass="doc"><p>This module lets you implement <code><ahref="Servant-Server.html#t:Server">Server</a></code>s for defined APIs. You'll
</pre></td></tr></table></div></div></div><divclass="top"><pclass="src"><spanclass="keyword">newtype</span><aname="t:RouteResult"class="def">RouteResult</a> a <ahref="src/Servant-Server.html#RouteResult"class="link">Source</a></p><divclass="doc"><p>A wrapper around <code><code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Either.html#t:Either">Either</a></code><code><ahref="Servant-Server.html#t:RouteMismatch">RouteMismatch</a></code> a</code>.</p></div><divclass="subs constructors"><pclass="caption">Constructors</p><table><tr><tdclass="src"><aname="v:RR"class="def">RR</a></td><tdclass="doc empty"> </td></tr><tr><tdcolspan="2"><divclass="subs fields"><pclass="caption">Fields</p><dl><dtclass="src"><aname="v:routeResult"class="def">routeResult</a> :: <ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Either.html#t:Either">Either</a><ahref="Servant-Server.html#t:RouteMismatch">RouteMismatch</a> a</dt><ddclass="doc empty"> </dd></dl><divclass="clear"></div></div></td></tr></table></div><divclass="subs instances"><pid="control.i:RouteResult"class="caption collapser"onclick="toggleSection('i:RouteResult')">Instances</p><divid="section.i:RouteResult"class="show"><table><tr><tdclass="src"><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Eq.html#t:Eq">Eq</a> a =><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Eq.html#t:Eq">Eq</a> (<ahref="Servant-Server.html#t:RouteResult">RouteResult</a> a)</td><tdclass="doc empty"> </td></tr><tr><tdclass="src"><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Text-Show.html#t:Show">Show</a> a =><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Text-Show.html#t:Show">Show</a> (<ahref="Servant-Server.html#t:RouteResult">RouteResult</a> a)</td><tdclass="doc empty"> </td></tr><tr><tdclass="src"><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Monoid.html#t:Monoid">Monoid</a> (<ahref="Servant-Server.html#t:RouteResult">RouteResult</a> a)</td><tdclass="doc"><p>If we get a <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Either.html#v:Right">Right</a></code>, it has precedence over everything else.</p><p>This in particular means that if we could get several <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Either.html#v:Right">Right</a></code>s,
only the first we encounter would be taken into account.</p></td></tr></table></div></div></div><divclass="top"><pclass="src"><aname="v:failWith"class="def">failWith</a> :: <ahref="Servant-Server.html#t:RouteMismatch">RouteMismatch</a> -><ahref="Servant-Server.html#t:RouteResult">RouteResult</a> a <ahref="src/Servant-Server.html#failWith"class="link">Source</a></p></div><divclass="top"><pclass="src"><aname="v:succeedWith"class="def">succeedWith</a> :: a -><ahref="Servant-Server.html#t:RouteResult">RouteResult</a> a <ahref="src/Servant-Server.html#succeedWith"class="link">Source</a></p></div><divclass="top"><pclass="src"><aname="v:isMismatch"class="def">isMismatch</a> :: <ahref="Servant-Server.html#t:RouteResult">RouteResult</a> a -><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Bool.html#t:Bool">Bool</a><ahref="src/Servant-Server.html#isMismatch"class="link">Source</a></p></div><divclass="top"><pclass="src"><spanclass="keyword">type</span><aname="t:RoutingApplication"class="def">RoutingApplication</a><ahref="src/Servant-Server.html#RoutingApplication"class="link">Source</a></p><divclass="subs arguments"><pclass="caption">Arguments</p><table><tr><tdclass="src"> = <ahref="https://hackage.haskell.org/package/wai-3.0.2/docs/Network-Wai.html#t:Request">Request</a></td><tdclass="doc"><p>the request, the field <code><ahref="https://hackage.haskell.org/package/wai-3.0.2/docs/Network-Wai.html#v:pathInfo">pathInfo</a></code> may be modified by url routing</p></td></tr><tr><tdclass="src">-> (<ahref="Servant-Server.html#t:RouteResult">RouteResult</a><ahref="https://hackage.haskell.org/package/wai-3.0.2/docs/Network-Wai.html#t:Response">Response</a> -><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/System-IO.html#t:IO">IO</a><ahref="https://hackage.haskell.org/package/wai-3.0.2/docs/Network-Wai.html#t:ResponseReceived">ResponseReceived</a>)</td><tdclass="doc empty"> </td></tr><tr><tdclass="src">-><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/System-IO.html#t:IO">IO</a><ahref="https://hackage.haskell.org/package/wai-3.0.2/docs/Network-Wai.html#t:ResponseReceived">ResponseReceived</a></td><tdclass="doc empty"> </td></tr></table></div></div><divclass="top"><pclass="src"><spanclass="keyword">class</span><aname="t:HasServer"class="def">HasServer</a> layout <spanclass="keyword">where</span><ahref="src/Servant-Server.html#HasServer"class="link">Source</a></p><divclass="subs associated-types"><pclass="caption">Associated Types</p><pclass="src"><spanclass="keyword">type</span><aname="t:Server"class="def">Server</a> layout :: * <ahref="src/Servant-Server.html#Server"class="link">Source</a></p></div><divclass="subs methods"><pclass="caption">Methods</p><pclass="src"><aname="v:route"class="def">route</a> :: <ahref="Servant.html#t:Proxy">Proxy</a> layout -><ahref="Servant-Server.html#t:Server">Server</a> layout -><ahref="Servant-Server.html#t:RoutingApplication">RoutingApplication</a><ahref="src/Servant-Server.html#route"class="link">Source</a></p></div><divclass="subs instances"><pid="control.i:HasServer"class="caption collapser"onclick="toggleSection('i:HasServer')">Instances</p><divid="section.i:HasServer"class="show"><table><tr><tdclass="src"><ahref="Servant-Server.html#t:HasServer">HasServer</a><ahref="Servant-API-Delete.html#t:Delete">Delete</a></td><tdclass="doc"><p>If you have a <code><ahref="Servant-API-Delete.html#t:Delete">Delete</a></code> endpoint in your API,
the handler for this endpoint is meant to delete
a resource.</p><p>The code of the handler will, just like
for <code><ahref="Servant-API-Get.html#t:Get">Get</a></code>, <code><ahref="Servant-API-Post.html#t:Post">Post</a></code> and
<code><ahref="Servant-API-Put.html#t:Put">Put</a></code>, run in <code>EitherT (Int, String) IO ()</code>.
The <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Int.html#t:Int">Int</a></code> represents the status code and the <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-String.html#t:String">String</a></code> a message
to be returned. You can use <code><ahref="https://hackage.haskell.org/package/either-4.3.2/docs/Control-Monad-Trans-Either.html#v:left">left</a></code> to
painlessly error out if the conditions for a successful deletion
are not met.</p></td></tr><tr><tdclass="src"><ahref="Servant-Server.html#t:HasServer">HasServer</a><ahref="Servant-API-Raw.html#t:Raw">Raw</a></td><tdclass="doc"><p>Just pass the request to the underlying application and serve its response.</p><p>Example:</p><pre>type MyApi = "images" :> Raw
server :: Server MyApi
server = serveDirectory "/var/www/images"</pre></td></tr><tr><tdclass="src"><ahref="https://hackage.haskell.org/package/aeson-0.8.0.2/docs/Data-Aeson-Types.html#t:ToJSON">ToJSON</a> result =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Get.html#t:Get">Get</a> result)</td><tdclass="doc"><p>When implementing the handler for a <code><ahref="Servant-API-Get.html#t:Get">Get</a></code> endpoint,
just like for <code><ahref="Servant-API-Delete.html#t:Delete">Delete</a></code>, <code><ahref="Servant-API-Post.html#t:Post">Post</a></code>
and <code><ahref="Servant-API-Put.html#t:Put">Put</a></code>, the handler code runs in the
<code>EitherT (Int, String) IO</code> monad, where the <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Int.html#t:Int">Int</a></code> represents
the status code and the <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-String.html#t:String">String</a></code> a message, returned in case of
failure. You can quite handily use <code><ahref="Control-Monad-Trans-EitherT.html#v:left">left</a></code>
to quickly fail if some conditions are not met.</p><p>If successfully returning a value, we just require that its type has
a <code><ahref="https://hackage.haskell.org/package/aeson-0.8.0.2/docs/Data-Aeson-Types.html#t:ToJSON">ToJSON</a></code> instance and servant takes care of encoding it for you,
yielding status code 200 along the way.</p></td></tr><tr><tdclass="src"><ahref="https://hackage.haskell.org/package/aeson-0.8.0.2/docs/Data-Aeson-Types.html#t:ToJSON">ToJSON</a> a =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Post.html#t:Post">Post</a> a)</td><tdclass="doc"><p>When implementing the handler for a <code><ahref="Servant-API-Post.html#t:Post">Post</a></code> endpoint,
just like for <code><ahref="Servant-API-Delete.html#t:Delete">Delete</a></code>, <code><ahref="Servant-API-Get.html#t:Get">Get</a></code>
and <code><ahref="Servant-API-Put.html#t:Put">Put</a></code>, the handler code runs in the
<code>EitherT (Int, String) IO</code> monad, where the <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Int.html#t:Int">Int</a></code> represents
the status code and the <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-String.html#t:String">String</a></code> a message, returned in case of
failure. You can quite handily use <code><ahref="Control-Monad-Trans-EitherT.html#v:left">left</a></code>
to quickly fail if some conditions are not met.</p><p>If successfully returning a value, we just require that its type has
a <code><ahref="https://hackage.haskell.org/package/aeson-0.8.0.2/docs/Data-Aeson-Types.html#t:ToJSON">ToJSON</a></code> instance and servant takes care of encoding it for you,
yielding status code 201 along the way.</p></td></tr><tr><tdclass="src"><ahref="https://hackage.haskell.org/package/aeson-0.8.0.2/docs/Data-Aeson-Types.html#t:ToJSON">ToJSON</a> a =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Put.html#t:Put">Put</a> a)</td><tdclass="doc"><p>When implementing the handler for a <code><ahref="Servant-API-Put.html#t:Put">Put</a></code> endpoint,
just like for <code><ahref="Servant-API-Delete.html#t:Delete">Delete</a></code>, <code><ahref="Servant-API-Get.html#t:Get">Get</a></code>
and <code><ahref="Servant-API-Post.html#t:Post">Post</a></code>, the handler code runs in the
<code>EitherT (Int, String) IO</code> monad, where the <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Int.html#t:Int">Int</a></code> represents
the status code and the <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-String.html#t:String">String</a></code> a message, returned in case of
failure. You can quite handily use <code><ahref="Control-Monad-Trans-EitherT.html#v:left">left</a></code>
to quickly fail if some conditions are not met.</p><p>If successfully returning a value, we just require that its type has
a <code><ahref="https://hackage.haskell.org/package/aeson-0.8.0.2/docs/Data-Aeson-Types.html#t:ToJSON">ToJSON</a></code> instance and servant takes care of encoding it for you,
yielding status code 200 along the way.</p></td></tr><tr><tdclass="src">(<ahref="Servant-Server.html#t:HasServer">HasServer</a> a, <ahref="Servant-Server.html#t:HasServer">HasServer</a> b) =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Alternative.html#t::-60--124--62-">(:<|>)</a> a b)</td><tdclass="doc"><p>A server for <code>a <code><ahref="Servant-API-Alternative.html#t::-60--124--62-">:<|></a></code> b</code> first tries to match the request again the route
represented by <code>a</code> and if it fails tries <code>b</code>. You must provide a request
handler for each route.</p><pre>type MyApi = "books" :> Get [Book] -- GET /books
:<|>"books" :> ReqBody Book :> Post Book -- POST /books
server :: Server MyApi
server = listAllBooks :<|> postBook
where listAllBooks = ...
postBook book = ...</pre></td></tr><tr><tdclass="src">(<ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:KnownSymbol">KnownSymbol</a> capture, <ahref="Servant-Common-Text.html#t:FromText">FromText</a> a, <ahref="Servant-Server.html#t:HasServer">HasServer</a> sublayout) =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Sub.html#t::-62-">(:>)</a> * (<ahref="Servant-API-Capture.html#t:Capture">Capture</a><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:Symbol">Symbol</a> * capture a) sublayout)</td><tdclass="doc"><p>If you use <code><ahref="Servant-API-Capture.html#t:Capture">Capture</a></code> in one of the endpoints for your API,
this automatically requires your server-side handler to be a function
that takes an argument of the type specified by the <code><ahref="Servant-API-Capture.html#t:Capture">Capture</a></code>.
This lets servant worry about getting it from the URL and turning
it into a value of the type you specify.</p><p>You can control how it'll be converted from <code><ahref="https://hackage.haskell.org/package/text-1.2.0.0/docs/Data-Text.html#t:Text">Text</a></code> to your type
by simply providing an instance of <code><ahref="Servant-Common-Text.html#t:FromText">FromText</a></code> for your type.</p><p>Example:</p><pre>type MyApi = "books" :> Capture "isbn" Text :> Get Book
server :: Server MyApi
server = getBook
where getBook :: Text -> EitherT (Int, String) IO Book
getBook isbn = ...</pre></td></tr><tr><tdclass="src">(<ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:KnownSymbol">KnownSymbol</a> sym, <ahref="Servant-Server.html#t:HasServer">HasServer</a> sublayout) =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Sub.html#t::-62-">(:>)</a> * (<ahref="Servant-API-QueryParam.html#t:QueryFlag">QueryFlag</a><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:Symbol">Symbol</a> sym) sublayout)</td><tdclass="doc"><p>If you use <code><code><ahref="Servant-API-QueryParam.html#t:QueryFlag">QueryFlag</a></code>"published"</code> 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 <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Bool.html#t:Bool">Bool</a></code>.</p><p>Example:</p><pre>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...</pre></td></tr><tr><tdclass="src">(<ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:KnownSymbol">KnownSymbol</a> sym, <ahref="Servant-Common-Text.html#t:FromText">FromText</a> a, <ahref="Servant-Server.html#t:HasServer">HasServer</a> sublayout) =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Sub.html#t::-62-">(:>)</a> * (<ahref="Servant-API-QueryParam.html#t:QueryParams">QueryParams</a><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:Symbol">Symbol</a> * sym a) sublayout)</td><tdclass="doc"><p>If you use <code><code><ahref="Servant-API-QueryParam.html#t:QueryParams">QueryParams</a></code>"authors" Text</code> 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 <code>[<code>Text</code>]</code>.</p><p>This lets servant worry about looking up 0 or more values in the query string
associated to <code>authors</code> and turning each of them into a value of
the type you specify.</p><p>You can control how the individual values are converted from <code>Text</code> to your type
by simply providing an instance of <code><ahref="Servant-Common-Text.html#t:FromText">FromText</a></code> for your type.</p><p>Example:</p><pre>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...</pre></td></tr><tr><tdclass="src">(<ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:KnownSymbol">KnownSymbol</a> sym, <ahref="Servant-Common-Text.html#t:FromText">FromText</a> a, <ahref="Servant-Server.html#t:HasServer">HasServer</a> sublayout) =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Sub.html#t::-62-">(:>)</a> * (<ahref="Servant-API-QueryParam.html#t:QueryParam">QueryParam</a><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:Symbol">Symbol</a> * sym a) sublayout)</td><tdclass="doc"><p>If you use <code><code><ahref="Servant-API-QueryParam.html#t:QueryParam">QueryParam</a></code>"author" Text</code> 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 <code><code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Maybe.html#t:Maybe">Maybe</a></code><code>Text</code></code>.</p><p>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 <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Maybe.html#t:Maybe">Maybe</a></code>, because it may not be there and servant would then
hand you <code><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/Data-Maybe.html#v:Nothing">Nothing</a></code>.</p><p>You can control how it'll be converted from <code>Text</code> to your type
by simply providing an instance of <code><ahref="Servant-Common-Text.html#t:FromText">FromText</a></code> for your type.</p><p>Example:</p><pre>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...</pre></td></tr><tr><tdclass="src">(<ahref="https://hackage.haskell.org/package/aeson-0.8.0.2/docs/Data-Aeson-Types.html#t:FromJSON">FromJSON</a> a, <ahref="Servant-Server.html#t:HasServer">HasServer</a> sublayout) =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Sub.html#t::-62-">(:>)</a> * (<ahref="Servant-API-ReqBody.html#t:ReqBody">ReqBody</a> * a) sublayout)</td><tdclass="doc"><p>If you use <code><ahref="Servant-API-ReqBody.html#t:ReqBody">ReqBody</a></code> in one of the endpoints for your API,
this automatically requires your server-side handler to be a function
that takes an argument of the type specified by <code><ahref="Servant-API-ReqBody.html#t:ReqBody">ReqBody</a></code>.
This lets servant worry about extracting it from the request and turning
it into a value of the type you specify.</p><p>All it asks is for a <code><ahref="https://hackage.haskell.org/package/aeson-0.8.0.2/docs/Data-Aeson-Types.html#t:FromJSON">FromJSON</a></code> instance.</p><p>Example:</p><pre>type MyApi = "books" :> ReqBody Book :> Post Book
server :: Server MyApi
server = postBook
where postBook :: Book -> EitherT (Int, String) IO Book
postBook book = ...insert into your db...</pre></td></tr><tr><tdclass="src">(<ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:KnownSymbol">KnownSymbol</a> path, <ahref="Servant-Server.html#t:HasServer">HasServer</a> sublayout) =><ahref="Servant-Server.html#t:HasServer">HasServer</a> (<ahref="Servant-API-Sub.html#t::-62-">(:>)</a><ahref="https://hackage.haskell.org/package/base-4.7.0.1/docs/GHC-TypeLits.html#t:Symbol">Symbol</a> path sublayout)</td><tdclass="doc"><p>Make sure the incoming request starts with <code>"/path"</code>, strip it and
pass the rest of the request path to <code>sublayout</code>.</p></td></tr></table></div></div></div></div></div><divid="footer"><p>Produced by <ahref="http://www.haskell.org/haddock/">Haddock</a> version 2.15.0</p></div></body></html>
