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