@@ -1,64 +1,10 @@
1−Servant tutorial
2−================
1+Tutorial
2+========
33
44This is an introductory tutorial to the current version of *servant*, which is
55**0.4**. Any comment or issue can be directed to `this website's issue
66tracker <http://github.com/haskell-servant/haskell-servant.github.io/issues>`_.
77
8−Github
9−-------
10−
11−- the servant packages: `haskell-servant/servant <https://github.com/haskell-servant/servant>`_
12−- the website (including this tutorial): `haskell-servant/haskell-servant.github.io <https://github.com/haskell-servant/haskell-servant.github.io/>`_
13−- Feel free to use the issue tracker (or to send PRs!) on the website's repository to give feedback and suggestions about this tutorial
14−
15−Introduction
16−-------------
17−
18−*servant* has the following guiding principles:
19−
20−- concision
21−
22− This is a pretty wide-ranging principle. You should be able to get nice
23− documentation for your web servers, and client libraries, without repeating
24− yourself. You should not have to manually serialize and deserialize your
25− resources, but only declare how to do those things *once per type*. If a
26− bunch of your handlers take the same query parameters, you shouldn't have to
27− repeat that logic for each handler, but instead just "apply" it to all of
28− them at once. Your handlers shouldn't be where composition goes to die. And
29− so on.
30−
31−- flexibility
32−
33− If we haven't thought of your use case, it should still be easily
34− achievable. If you want to use templating library X, go ahead. Forms? Do
35− them however you want, but without difficulty. We're not opinionated.
36−
37−- separation of concerns
38−
39− Your handlers and your HTTP logic should be separate. True to the philosphy
40− at the core of HTTP and REST, with *servant* your handlers return normal
41− Haskell datatypes - that's the resource. And then from a description of your
42− API, *servant* handles the *presentation* (i.e., the Content-Types). But
43− that's just one example.
44−
45−- type safety
46−
47− Want to be sure your API meets a specification? Your compiler can check
48− that for you. Links you can be sure exist? You got it.
49−
50−To stick true to these principles, we do things a little differently than you
51−might expect. The core idea is *reifying the description of your API*. Once
52−reified, everything follows. We think we might be the first web framework to
53−reify API descriptions in an extensible way. We're pretty sure we're the first
54−to reify it as *types*.
55−
56−To be able to write a webservice you only need to read the first two sections,
57−but the goal of this document being to get you started with servant, we also
58−cover the couple of ways you can extend servant for a great good.
59−
60−Tutorial
61−---------
628
639.. toctree::
6410 :maxdepth: 1