

Rest – A Haskell REST framework - bergmark
http://engineering.silk.co/post/90354057868/announcing-rest-a-haskell-rest-framework

======
ilyagr
I always thought that what makes Haskell particularly readable are the types:
to understand what a function does, it is often enough, and always helpful, to
understand what type it takes to what types.

So, when the first type I see in a Tutorial is

    
    
        Resource IO (ReaderT Title IO) Title () Void
    

I am confused. When, in addition, the functions are named

    
    
         mkResourceReader :: ??? -> Resource IO (ReaderT Title IO) Title () Void
    

I lose hope that I'll ever understand what's going on. Granted, it was only
recently that I understood what 'ReaderT Title IO' alone means.

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
    

does, and what its type is? It seems like that might be tractable.

~~~
sfvisser
I think your comments are valid and I mostly agree very much with this
sentiment. Thank you for sharing.

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.

~~~
ilyagr
There's nothing wrong with what you are doing. There is no law that states
that all open source libraries in the world should be perfectly documented,
and have a set of tutorials that would gently teach anyone as much as he wants
about how to use it. Writing documentation and/or tutorials is hard work, and
the larger your target audience is, the harder and more time-consuming it is.

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.

------
gambogi
I don't have the expertise to dissect this code, so I will choose instead to
criticize the name of the project. My opinion is valuable, relevant, and
provokes further discussion.

~~~
autodidakto
Instead of addressing the linked article, your post is insightful self-parody,
with much sarcasm -- a style more suited to reddit than hn. Please remove it
at once, preferably falling on your sword afterwards.

~~~
collyw
Where are the HN rules? I always see comments referencing the style of
comments that are encouraged / discouraged, without any actual reference.

------
niix
Very cool. I'm just getting into Haskell. Coming from the JS world, it's nice
to be able to start to learn similar things that I do as a JS developer. My
mind only thinks in the way of the web currently, so this helps my transition.
:)

------
MaxGabriel
Do you guys integrate this with Happstack/Wai/Snap at work, or do you use pure
rest or something?

~~~
bergmark
We use both the rest-happstack and rest-snap backends, rest-wai is brand new
so we haven't gotten around to using that one. You need to pick one of the
backends to run an api, rest doesn't contain a web server.

------
peaton
I know this was just released, but are there any open source projects that
currently use this?

~~~
bergmark
I haven't seen any projects except for rest-example
[https://github.com/silkapp/rest/tree/master/rest-
example](https://github.com/silkapp/rest/tree/master/rest-example)

But on the bright side we have been using this in production for a long time
:-)

------
lclarkmichalek
Interesting that they are using hs-src-exts, can the job not be done by
Template Haskell?

~~~
sfvisser
It could, but would be extremely messy. We think hs-src-exts is really the
right tool for the job here.

------
pepijndevos
Nice! I worked with this project when it was not yet public, and it's good. A
lot easier to use than what the monads might lead you to think. The generated
API clients are great too. Of course the Haskell client uses the same types as
the server, so you get type errors in the client if the API changed.

------
mark_l_watson
I have a Haskell project that exposes some NLP experiments in a Yesod web app.
I would also like to provide a REST interface, so this looks good.

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.

~~~
mark_l_watson
While this looks like a cool project, since I have already started using (and
like) Yesod, I am probably better off using Yesod's REST support
([http://www.yesodweb.com/book/restful-
content](http://www.yesodweb.com/book/restful-content))

------
gberger
Kind of a colliding name, huh?

~~~
dons
This would become "haskell-rest" in most package systems.

------
lukasm
Googlabilty of the name is really bad. Rename it to something else e.g. HRest

~~~
PMan74
Or Resth, (unless somebody in the lisp community bagged that one already)

~~~
anaphor
Nobody thought of Hest? I admit it does sound kind of silly though, but it's
got the 'H' at least, and it doesn't _sound_ like Rest.

~~~
Dewie
With that name you can get a mascot, too:

[http://en.bab.la/dictionary/danish-
english/hest](http://en.bab.la/dictionary/danish-english/hest)

~~~
dllthomas
No reason they can't use that mascot regardless!

------
thathonkey
"We've decided to call our REST framework - wait for it - Rest."

~~~
lelf
This thread's queue for useless bikeshedders is full, sorry.

~~~
thathonkey
I disagree that the name for something like this is a trivial decision.
Especially when considering the name for a framework which will need to be
discoverable on Google to gain popularity. And even more especially when you
choose to name the framework for working with a technological concept in one
specific programming language the same thing (albeit different casing) as that
technological concept itself.

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.

~~~
andrus
Google "haskell rest". Done. See @sfvisser's comment:
[https://news.ycombinator.com/item?id=7965468](https://news.ycombinator.com/item?id=7965468)

~~~
thathonkey
I fail to see how that solves the problem for anyone other than people who
already know that they're looking for a Haskell REST framework that might be
called Rest.

------
dpeck
Isn't writing out to the network a side effect?

Edit: Haskell folks are a bit touchy :) Just a joke, I use Xmonad, I'm cool
with y'all.

~~~
dllthomas
Generally, it is the desired _effect_. In Haskell, it will be reified in an IO
action, will appear in type signatures, and - as a value - can be manipulated
and combined with similar values. It will only be a _side_ effect if called
with unsafePerformIO or similar, and the Haskell community will rightly
condemn you for doing so (outside debugging) without a proof for why it's both
okay and necessary in this circumstance - relying on side effects means you
lose all kinds of guarantees that the type system usually affords you.

