Work on example and documentation showing how okapi can be used with servant.

Now that we have sessions, it should be possible to add CSRF protection. Maybe introduce constraint HasCSRFProtection m.

The introduction has the following example:

greet = do
  seg "greet"
  name <- pathParam
  returnPlainText [] $ "Hello " <> name <> "! I'm Okapi."

And say that this will set up a server that listens to http://localhost:3000/greeting/Bob.

I think that either should seg "greet" be changed to seg "greeting" or the URL should be changed to http://localhost:3000/greet/Bob.

This might not be possible without giving up the simplicity of Okapi, but maybe it is? Using WriterT or something similar would it be possible to generate OpenAPI docs? I've looked at final-tagless style and wondering if we can apply this to Okapi. We can "interpret" Okapi, both for parsing HTTP requests, and generating API docs. I'm just blabbering here. Any ideas?

Paper on tagless final/final tagless:
https://okmij.org/ftp/tagless-final/course/lecture.pdf

Defaults

• method should be GET
• no headers
• no body

Also need to provide functions for adding to a Request

Each page in the documentation has an Edit this page on GitHub link. However these links direct you to the non-existent (or private) repo https://github.com/MonadicSystems/okapi-docs.

123 Hello

To take Okapi to the next level, there should be logging. Should it be built in? Or left to the user? They are both possible. To add built-in logging, OkapiT will need WriterT. Or some other alternative because WriterT performance isn't great. The user could also just add WriterT in their custom monad stack. Should logging be built in or left to the user?

I really like the idea of Okapi, as I usually find myself wanting something more type-safe than Scotty, but easier to work with than Servant.

Unfortunately, version 0.1 on Hackage is basically unusable because of the way things are constantly dumped to stdout. Plus, there's little documentation, and what there is contains broken links and examples which don't compile. But it is a version 0.1, and you've mentioned that it's an early and experimental release, so that's fine!

What I'm curious about is that the wiki describes a very different API, as mentioned in your Reddit post, which looks like a great improvement (the overall idea anyway - I could quibble about minor things like having to import so much qualified). But it's not clear whether it's even possible to use it yet. The examples don't compile with the current main branch, and there are other newer branches floating around, which mostly don't build at all.

So, is there a commit anywhere with which it is possible to use the new API, or do we just need to wait for things to stabilise? I'm using 0.1 for now on a small, low-stakes personal project, so I really don't mind breaking changes or the occasional bug, and I'd be happy to act as a sort of beta tester.

Should look something like:

-- type MonadServer m = (MonadRequest m, MonadResponse m)

class (MonadRequest m, MonadResponse m) => MonadServer m where
  throw :: ...
  next :: ...

class Monad m => MonadRequest m where
  pathParam :: ...
  queryParam :: ...

class Monad m => MonadResponse m where
  write :: forall a. Writeable a => a -> m ()

to make Okapi functions more descriptive and to constrain their abilities accordingly. Inspired by "IO Monad Considered Harmful". Don't know if this would work.

Using https://hackage.haskell.org/package/wai-extra-3.1.8/docs/Network-Wai-Test.html

As it is right now, you have to add optional $ seg "" to handle trailing slashes at the beginning of your parser.

I can do this two ways:

1. Introduce IO into the MonadOkapi stack and parse multipart form data inside a Okapi parser
2. Parse the multipart form data from the request before it is passed into Okapi. We can avoid introducing IO into the MonadOkapi constraint this way. Have to change Body to sum type representing the different types of form data.

https://hackage.haskell.org/package/megaparsec-9.2.0/docs/Text-Megaparsec.html#t:MonadParsec

Add MonadOkapi similar in concept to MonadParsec to make things more abstract.

Currently, errors provide no information as to what caused the error. Aborts only provide an HTTP error response, which may give a little idea of what caused it. Skip errors provide no information at all. Skip errors should at least provide an idea of what parser caused the error. To do this, the Skip data constructor can take an additional Text argument to say what happened. Abort issues could have the same. Then the issue becomes, how should the Monoid instance work? We want to see all the errors that happened so discarding them is not an option. The parser will have to return a [Error] instead of just Error.