## Introduction Okapi is a microframework for web development in Haskell based on monadic parsing. The inspiration for Okapi originally came from looking at web frameworks in other language ecosystems such as Python’s Flask, Nim’s Jester, OCaml’s Dream, and F#’s Giraffe, which the name of this Haskell framework is related to. I noticed that many Haskell web frameworks tend to require a lot of boilerplate code, and/or make use of a lot of advanced type level language features that make it hard to understand the internals of the framework. The goal of Okapi is to create a Haskell web framework with an ergonomic developer experience that is idiomatic to the host language. ## Parsers In Haskell, a simple `String` parser can be modeled as a function with the type `String -> (Either ParserError a, String)`. This function takes values of type `String` and returns either a `ParserError` (if it fails) or a value of some type `a` (if it succeeds), along with a new `String` that's missing the characters that were consumed by the parsing function. We could use the function like so: ```haskell ``` This is great, but issues start to arise when we try to compose parsers with other parsers. For example, let's say we wanted to parse blah blah: ```haskell ``` To avoid the explicit passing of state from one parser to the next, we can use monads. You may have already noticed that the type of our parser can be simplified with the `State String` monad. We can transform our function of type `String -> (Either ParseError a, String)` to a value of type `State String (Either ParserError a)`. A value of type `State String (Either ParserError a)` represents a value of type `Either ParserError a` that was computed in a stateful context, where the state is of type `String`. Now that our parser is defined as a monad we can use `do` notation , and it becomes easier to compose our parsers with other parsers because we don't have to manually pass the state from a previous parser to the next one. Let's try the parser composition we tried above with our new parser definition: ```haskell ``` As you can see our parsers compose a lot better, but we still have to explicitly handle the result of the parsers because they may return a `ParserError`. Functions that return values of the type `Either ParserError a` can be modelled using the `Except ParserError` monad. A value of the type `Except ParserError a` represents a value of type `a` that is computed in a context that may not succeed, but instead throw an error value of type `ParserError`. In our case we want our parser's computations to happen in a context in which there is state of type `String`, and the possibilty of throwing an error value of type `ParserError`. To get both of these useful abilities, let's combine the `Except ParserError` monad with our `State String` monad using monad transformers. Our simplified parser now has the type `ExceptT ParserError (State String a)`, where `ExceptT` is a monad transformer that gives our base `State String` monad the ability to throw error values of type `ParserError` upon failure. To make the code examples easier on our eyes, let's make a type synonym defined as `type Parser a = ExceptT ParserError (State String a)`. Now, any value anottated with the type `Parser a` represents a value of some type `a` that is computed in a context that has access to state of type `String` AND may throw error values of type `ParserError` upon failing. Let's redefine the example we defined above: ```haskell ``` Great. ## HTTP Request Parsers Now, let's redefine `type Parser a = ExceptT ParserError (State String a)` as `type Parser a = ExceptT HTTPError (State HTTPRequest a)`. This is an HTTP Request Parser. Instead of parsing happening in a context where the computation has access to state of type `String` and can throw errors of type `ParserError`, it happens in a context where the computation has access to state of type `HTTPRequest` and can throw errors of type `HTTPError`. Just like the string parser above had a concept of "consuming" parts of a `String`, the HTTP request parser "consumes" values of the type `HTTPRequest`. By consume we mean .... If you break values of type `String` into its smallest consituents, you get values of type `Char`. A `String` value is a list of `Char` values. What are the smallest constituents of a `HTTPRequest` value? The data type `HTTPRequest` is defined as follows: ```haskell data HTTPRequest = HTTPRequest { method :: Method , path :: [Text] , query :: Query , body :: ByteString , headers :: Headers } ``` Our HTTP request parser consumes different parts of the HTTP request like the `method` and `query`. Once a piece of the HTTP request is parsed, it is removed from the request before it is implicitly passed to the next parser. There are 2 types of parsers: 1. Data parsers 2. Checker parsers There are 5 types of parsers for each of the 5 parts of a HTTP request. 1. Method Parsers ```haskell method :: MonadOkapi m => m Method matchMethod :: MonadOkapi m => Method -> m () get :: MonadOkapi m => m () get = matchMethod "GET" ``` 2. Path Parsers ```haskell path :: MonadOkapi m => m Path -- Parses entire remaining path path = many seg seg :: MonadOkapi m => m Text matchPath :: MonadOkapi m => Path -> m () matchPath desiredPath = mapM_ matchSeg desiredPath matchSeg :: MonadOkapi m => Text -> m () pathParam :: MonadOkapi m => FromHttpApiData a => m a pathEnd :: MonadOkapi m => m () ``` 4. Query Parsers ```haskell query :: MonadOkapi m => m Query -- parses entire query queryParam :: MonadOkapi m => FromHttpApiData a => Text -> m a queryFlag :: MonadOkapi m => Text -> m () queryParamRaw :: Text -> m Text ``` 6. Body Parsers ```haskell body :: MonadOkapi m => m Body bodyJSON :: MonadOkapi m, FromJSON a => m a bodyURLEncoded :: FromForm a, MonadOkapi m => m a bodyMultipart :: FromForm a, MonadOkapi m => m (a, [File]) ``` 8. Headers Parsers ```haskell headers :: MonadOkapi m => m Headers header :: MonadOkapi m => HeaderName -> m Header cookie :: MonadOkapi m => m Cookie crumb :: MonadOkapi m => Text -> m Crumb ``` We can use these to create increasingly complex parsers. For example, let's say we wanted to implement a HTTP parser that matches the request `GET /blog`. That would look like this: ```haskell blogRoute :: Parser () blogRoute = do get -- Make sure that the request is a GET request matchSeg "blog" -- Match against the path segment /blog pathEnd -- Make sure that there are no more path segments remaining in the request ``` Just like earlier, with our monadic string parser, we can sequence HTTP request parsers using `do` notation. This request parser isn't really useful though because it doesn't return anything. Let's make it return a response: ```haskell blogRoute :: Parser HTTPResponse blogRoute = do get matchSeg "blog" pathEnd return ok ``` Now if we run our parser, it will return a `200 OK` response if we send a `GET` request to the `/blog` endpoint. On top of being able to sequence parsers with `do` notation thanks to `Parser` being an instance of the `Monad` typeclass, we can also build parsers that "choose" between multiple subparsers. This is possible because the `Parser` type is also an instance of the `Alternative` typeclass, which provides the `<|>` operator. Explain `<|>` then explain we can also parser combinators like `many`, `some`, `optional`, `option`, `takeWhile`, etc. Then explain the two types of errors and how to throw and catch them. Then explain returning responses and executing a parser. Explaining type safe URLs with patterns: ## Patterns Okapi uses bi-directional patterns to have typesafe urls. So you would have something like: ```haskell -- Matches routes of the form /blog/99 pattern BlogRoute :: Int -> Path pattern BlogRoute uuid <- ["blog", PathParam uuid] where BlogRoute uuid = ["blog", PathParam uuid] ``` or just ```haskell -- Bidriectional Implicit pattern BlogRoute :: Int -> Path pattern BlogRoute uuid = ["blog", PathParam uuid] pattern BlogCategoryRoute :: Text -> Path pattern BlogCategoryRoute category = ["blog", PathParam category] ``` uses these bidrectional patterns with the `route` parser, like so: ```haskell route :: MonadOkapi m => (Path -> m Response) -> m Response route matcher = do path <- parsePath matcher path myAPI :: MonadOkapi m => m Response myAPI = route $ \case BlogRoute uuid -> do get return ok BlogRouteCategory category -> do get mbOrderBy <- optional $ queryParam @Order "order" case mbOrderBy of Nothing -> do ... return ok Just orderBy -> do ... return ok _ -> next ``` Since both routes are `GET` requests, let's factor out the `get` parser: ```haskell myAPI :: MonadOkapi m => m Response myAPI = do get route $ \case BlogRoute uuid -> return ok BlogRouteCategory category -> do mbOrderBy <- optional $ queryParam @Order "order" case mbOrderBy of Nothing -> do ... return ok Just orderBy -> do ... return ok _ -> next ``` ## URLs There are two types of URLs that you can generate with Okapi: 1. Relative URLs 2. Absolute URLs ```haskell data URL = URL { unURL :: Text } data RelURL = RelURL Path Query data AbsURL = AbsURL Scheme Host (Maybe Port) RelURL class ToURL a where render :: a -> URL instance ToURL Path where instance ToURL Query where instance ToURL RelURL where render (RelURL p q) = render p <> render q instance ToURL AbsURL where instance ToURL Request where blogRouteCategoryURL = render $ BlogRouteCategory "fiction" class ToURL a => Matchable a where match :: (a -> m Response) -> m Response route :: (Path -> m Response) -> m Response routeWithQuery :: (RelURL -> m Response) -> m Response routeVirtual :: (AbsURL -> m Response) -> m Response ```