Flatten (a Proxy to) an API type.

This performs a number of transformations on the API type so as to end up with all combinators distributed over endpoints. For example, the following API type:

  type API = Capture "foo" Int :>
    ( Capture "bar" String :>
        ( Get '[JSON] String :<|>
          ReqBody '[JSON] Int :> Post '[JSON] Int
        ) :<|>
      Get '[JSON] Int
    ) :<|>
    Get '[JSON] [String]
  

gets transformed into:

  Capture "foo" Int :> Capture "bar" String :> Get '[JSON] String :<|>
  Capture "foo" Int :> Capture "bar" String :> ReqBody '[JSON] Int :> Post '[JSON] Int :<|>
  Capture "foo" Int :> Get '[JSON] Int :<|>
  Get '[JSON] [String]
  

The main point of doing this is to avoid "nested types" for server-side handlers and client functions. See this cookbook recipe (particularly the notes on FactoringAPI) for more about "nested types".

To derive "flat" client functions for the API type above, API, you can do:

  getfoobar :<|> postfoobar :<|> getfoo :<|> getstrings
    = client $ flatten (Proxy :: Proxy API)
  

To serve an implementation for that API with "flat" handler types, you can do:

  -- we define all our handlers assuming all the arguments are distributed,
  -- and declare that this is an implementation for Flat API, not API.
  server :: Server (Flat API)
  server = (foo bar -> return $ show (foo + bar))
      :<|> (foo bar body -> return $ show (foo + bar - body^2))
      :<|> (foo -> return (foo * 2))
      :<|> (return ["hello", "world"])

  api :: Proxy API
  api = Proxy

  main :: IO ()
  main = Network.Wai.Handler.Warp.run 8080 $
    serve (flatten api) server
  

Flatten and transform the API type a little bit.

Completely flattens an API type by applying a few simple transformations. The goal is to end up with an API type where things like a :> (b :<|> c) are rewritten to a :> b :<|> a :> c, so as to have client with very simple types, instead of "nested clients".

Reassociates '(:|)' to the right.

Get the endpoints with given indices in the all-flat representation of the API type, glueing them together with :<|>.

Get the endpoint with given index in the all-flat representation of the API type.