diff --git a/doc/cookbook/generic/Generic.lhs b/doc/cookbook/generic/Generic.lhs index e057cad6..24463c20 100644 --- a/doc/cookbook/generic/Generic.lhs +++ b/doc/cookbook/generic/Generic.lhs @@ -1,4 +1,14 @@ -# Using generics +# Record-based APIs: the simple case + +This cookbook explains how to implement an API with a simple record-based +structure. We only deal with non-nested APIs in which every endpoint is on the same +level. + +If a you need nesting because you have different branches in your API tree, you +might want to jump directly to the [Record-based APIs: the nested records +case](../namedRoutes/NamedRoutes.html) cookbook that broaches the subject. + +Shall we begin? ```haskell {-# LANGUAGE DataKinds #-} @@ -110,7 +120,7 @@ main = do _ -> putStrLn "To run, pass 'run' argument: cabal new-run cookbook-generic run" ``` -## Using generics together with a custom monad +## Using record-based APIs together with a custom monad If your app uses a custom monad, here's how you can combine it with generics. @@ -121,9 +131,6 @@ data AppCustomState = type AppM = ReaderT AppCustomState Handler -apiMyMonad :: Proxy (ToServantApi Routes) -apiMyMonad = genericApi (Proxy :: Proxy Routes) - getRouteMyMonad :: Int -> AppM String getRouteMyMonad = return . show @@ -139,3 +146,4 @@ nt s x = runReaderT x s appMyMonad :: AppCustomState -> Application appMyMonad state = genericServeT (nt state) recordMyMonad +``` diff --git a/doc/cookbook/namedRoutes/NamedRoutes.lhs b/doc/cookbook/namedRoutes/NamedRoutes.lhs index 4302ad5b..17a45a4c 100644 --- a/doc/cookbook/namedRoutes/NamedRoutes.lhs +++ b/doc/cookbook/namedRoutes/NamedRoutes.lhs @@ -1,10 +1,16 @@ -# NamedRoutes - Using records to define APIs +# Record-based APIs: the nested records case *Available in Servant 0.19 or higher* Servant offers a very natural way of constructing APIs with nested records, called `NamedRoutes`. -This cookbook explains how to implement such nested-record-APIs using `NamedRoutes` through the example of a Movie Catalog. +This cookbook explains how to implement such nested-record-based-APIs using +`NamedRoutes` through the example of a Movie Catalog. +If you don't need the nested aspect of the record-based API, you might want to look at [Record-based +APIs: the simple +case](../generic/Generic.html) cookbook +which covers a simpler implementation in which every endpoint is on the same +level. First, we start by constructing the domain types of our Movie Catalog. After, we show you how to implement the API type with the NamedRoutes records. diff --git a/doc/cookbook/structuring-apis/StructuringApis.lhs b/doc/cookbook/structuring-apis/StructuringApis.lhs index a8a82258..a0e603f0 100644 --- a/doc/cookbook/structuring-apis/StructuringApis.lhs +++ b/doc/cookbook/structuring-apis/StructuringApis.lhs @@ -35,6 +35,11 @@ The first part, `FactoringAPI`, shows how we can endpoints, just like we turn `a * b + a * c` into `a * (b + c)` in algebra. +(It should be noted that the `(:<|>)` operator is not the only way of combining +endpoints with Servant. Other techniques are shown in subsequent cookbooks. See +[record-based alternative for implementing APIs](StructuringApis.html#record-based-alternative-for-implementing-apis)) + + ``` haskell -- Two endpoints: -- - GET /x/[?y=] @@ -203,3 +208,14 @@ main = run 8080 . serve api $ This program is available as a cabal project [here](https://github.com/haskell-servant/servant/tree/master/doc/cookbook/structuring-apis). + +## Record-based alternative for implementing APIs + +It should be noted that the `(:<|>)` is not the only way of combining endpoints. +Servant offers a convenient way to design APIs with records avoiding the ordering constraint of the operator. + +A simple case is approached in the [Record-based APIs: the simple +case](../generic/Generic.html) +cookbook, which deals with flat APIs where every endpoint is on the same level. +Also, a more complex example with nested record is discussed in [Record-based APIs: the nested +records case](../namedRoutes/NamedRoutes.html) in which we implement an API tree with many branches.