This module defines better resource routing for Scotty.
Scotty is defined in terms of "routes", whereas HTTP is defined in terms of "resources". This package adds a "resource" abstraction to the scotty ecosystem.
(note: All examples probably require -XOverloadedStrings)
Scotty comes out of the box with a way to model "routes". The problem is that "routes" is not the abstraction used by the HTTP standard and it can sometimes be tricky to write a perfectly correct HTTP service using the routes model (where "correct" is judged against rfc-2616). The most blatant, (and who knows, maybe the only) example of this problem is shown by the scotty code:
import Web.Scotty.Trans (get, scottyT, text) ... scottyT 8080 id $ do get "/hello" $ do text "world"
If a client requests something like
DELETE /hello, this scotty application
404 Not Found, which conflicts with section 5.1.1 of rfc-2616.
A better response would be
405 Method Not Allowed, and it would include an
Allow response header.
This library gives users a way to model "resources" which is closer to the abstractions used in the HTTP standard.
We can re-write the above example like this:
import Web.Scotty.Trans (scottyT, text) import Web.Scotty.Resource.Trans (resource, get) ... scottyT 8080 id $ do resource "/hello" $ do get $ do text "world"
Given a request:
DELETE /hello HTTP/1.1 Host: localhost:8080
The resource-based scotty application will produce something like:
HTTP/1.1 405 Method Not Allowed Allow: GET
Each resource is described by a
WebResource value, which happens to be a
Monad. The only reason
Monad to fit in with the
do-notation coding style of
ScottyT. This is an abuse of
Monad, but, you
know, whatever. The
Monoid typeclass more correctly represents what a
WebResource really is. The
Monoid typeclasses are used to
compose instances of
Here is another more complex example, with multiple resources.
import Data.Aeson (decode) import Network.HTTP.Types (notFound404, badRequest400, noContent204) import Web.Scotty.Resource.Trans (resource, get, post) import Web.Scotty.Trans (scottyT, text, body, raw, status, param) import MyApplication (lookupPerson, storePerson) ... scottyT 8080 id $ do -- an "echo" resource resource "/echo" $ do get $ do text "hello world" post $ do -- echo the request body back to the user raw =<< body -- A resource that represents a kind of a RESTful database of people. -- This resource supports GET and PUT. resource "/people/:personId" $ do get $ do personId <- param "personId" maybePerson <- lookupPerson personId case maybePerson of Nothing -> status notFound404 Just person -> json person put $ do personId <- param "personId" maybePerson <- decode <$> body case maybePerson of Nothing -> do status badRequest400 text "Invalid person JSON" Just person -> storePerson personId person status noContent204