git.iko.soy/typeable/servant
on bump-ci help sign in
typeable/servant/doc/principles.rst
40 lines 1.7 kB history raw
1Principles
2----------
4**servant** has the following guiding principles:
6- concision
8 This is a pretty wide-ranging principle. You should be able to get nice
9 documentation for your web servers, and client libraries, without repeating
10 yourself. You should not have to manually serialize and deserialize your
11 resources, but only declare how to do those things *once per type*. If a
12 bunch of your handlers take the same query parameters, you shouldn't have to
13 repeat that logic for each handler, but instead just "apply" it to all of
14 them at once. Your handlers shouldn't be where composition goes to die. And
15 so on.
17- flexibility
19 If we haven't thought of your use case, it should still be easily
20 achievable. If you want to use templating library X, go ahead. Forms? Do
21 them however you want, but without difficulty. We're not opinionated.
23- separation of concerns
25 Your handlers and your HTTP logic should be separate. True to the philosophy
26 at the core of HTTP and REST, with **servant** your handlers return normal
27 Haskell datatypes - that's the resource. And then from a description of your
28 API, **servant** handles the *presentation* (i.e., the Content-Types). But
29 that's just one example.
31- type safety
33 Want to be sure your API meets a specification? Your compiler can check
34 that for you. Links you can be sure exist? You got it.
36To stick true to these principles, we do things a little differently than you
37might expect. The core idea is *reifying the description of your API*. Once
38reified, everything follows. We think we might be the first web framework to
39reify API descriptions in an extensible way. We're pretty sure we're the first
40to reify it as *types*.