Rest – A Haskell REST framework
engineering.silk.co
engineering.silk.co
So, when the first type I see in a Tutorial is
Resource IO (ReaderT Title IO) Title () Void
mkResourceReader :: ??? -> Resource IO (ReaderT Title IO) Title () Void
I wonder, is there a simple explanation for what's going on, or is the problem at hand really so complicated that this is the easiest way to explain it?
For example, maybe there should be a shorter and clearer name for the type 'Resource a (ReaderT b a) b () Void'? What does one do with resources -- I can only see them plugged into the 'route' function.
At this point I started cursing that I can't find the Haddock documentation anywhere, and I'm too lazy to search through github.
I'm sorry if this comes across as unfriendly to the author of the library, but I hope it's helpful to see what a person who tries to understand what it does might go through. The more I look at it, the more I think that everything could be fixed with a better tutorial.
EDIT It's late at night, and I'm rambling, but perhaps it would be enough to explain in the tutorial what the composition
route . mkResourceReader
But let's look at it differently.
This framework has been developed and shaped over a few years in a corporate environment by a small team of relatively experienced Haskell programmers. The code has been shaped and tweaked to specifically tailor all the needs we had at Silk for a effortless development of a very consistent REST API for our core product. The code solves a lot of problems at once.
We never developed this framework as a minimal library for public use. But, because it solves and actual problem for us and is very general purpose we felt obliged to open source it. This might be very useful for other as well.
One of incentives for a company to open source an internally used framework is to get community feedback that might end up shaping the software to be simpler, more generally applicable and more battle tested. That's why your critique is useful and exactly one of the reasons to opens source.
To go more in the why the types for a Resource are what they are right now:
- In a real world example your API probably doesn't run in IO, but in some monadic context that allows acces to you database, configuration settings, log server, S3 buckets etc.
- Resources contain a schema type that statically enforce the invariant that no routes will ever overlap in the server.
- A single resource, or multiple resources, can be identified by multiple identifiers (e.g. a user by uuid, e-mail, or last name). We require a total mapping from identifier to resource action.
- While stepping deeper into an API (path segment by path segment) we can learn more about our context and pass information down to sub-resources. We do this by extending the context, in the simplest case with a reader.
- The `route` function builds up an existential. So it looks like the type of the Resource is irrelevant and could be one simple type synonym, but it isn't. It's different every time and carries a lot of static information about the resource used at runtime, and for code and documentation generation.
We'd love to hear how we can simplify this.
I don't think your library will be generally useful to a large audience until you or someone else writes better documentation for it. But you don't have to target a large audience. It's quite likely that when someone else has the same problem, it would be faster for them to reuse your library than to write their own. They might even document the process.
I don't think I'm qualified to give any specific advice, but here's some general suggestions which may or may not be to the point. If you are sufficiently motivated, you should decide who your target audience is, and write enough documentation for them. For example, for an advanced audience, it might be useful to say a few words the general design of your library, explain which problems your library does solve and (more importantly) what the limitations of the design are, perhaps outline anything in the design that is strange or unexpected, but useful from your experience. The most important thing for them to know quickly is whether your library can actually solve their problem (which is probably slightly different from the problem you solved), whether it is actually faster to use your library than to roll their own. If they really need to, they'll figure out the rest. The end result might be closer in style to a CS paper than a tutorial.
Oh, and one thing you really should fix: it is annoying that the haddock documentation is not available on Hackage at the moment, and probably not searchable on Hoogle as well.
Again, there's nothing wrong with your library, you are doing a good thing open sourcing it, and any time you put in describing it and explaining it to people is valuable. Just keep doing more of what you are already doing.
But on the bright side we have been using this in production for a long time :-)
That said, I found nothing in the documentation for using this with Yesod and the developers seem to best support happstack.
I am a newbie at using Haskell for web apps, so I need to dig into the possibility of mixing happstack and Yesod in one app.
What motivates people to name projects after simple, common words?
Strikes me as a conceptual land-grab.
Similarly, `lens` right now has pretty much everything under the sun about lenses, though some prefer the simpler lens packages like `lens-family`.
I kind of feel less confident about the choice around `rest` since there are many interpretations and implementation choices which may lead to a desire for competition here. But I'll reserve actual judgement until I use it. I wouldn't at all mind a comprehensive, provably correct webmachine-like implementation of REST called `rest`.
I feel the same about lens :)
Note that we didn't even upload a package called 'rest'. We uploaded a family of packages starting with 'rest-'.
You guys just better earn your keep on that name ;)
How is that not a really important decision that should be considered practically? If I want to query Google for REST vs. Rest, or even converse with people about it, you don't think that will quickly become (needlessly) confusing assuming the framework becomes popular? And if you aren't expecting the framework to become popular, does that make it OK to choose such a lazy name?
But, hey, at least you got to namedrop the term "bikeshedding" along with your highly specious argument.
Edit: Haskell folks are a bit touchy :) Just a joke, I use Xmonad, I'm cool with y'all.