Snap.Snaplet.Rest

Serving resources

serveResource :: (HasResourceConfig b, FromRequest id) => Resource res (Handler b b) id diff -> Handler b b ()

Serve the specified resource using the configuration in the monad.

serveResourceWith :: (MonadSnap m, FromRequest id) => Resource res m id diff -> ResourceConfig m -> m ()

Serve the specified resource using the given configuration.

Resource

data Resource res m id diff

A resource descriptor for the type res. The resource runs in the monad m, identifies resources with values of the type id, and describes changes with value of the type diff.

resource :: Resource res m id diff

The empty resource descriptor, useful as a starting point for building resources.

addMedia :: Monad m => Media res m diff int -> ResourceBuilder res m id diff

Add a media representation for rendering and parsing.

setCreate :: (res -> m ()) -> ResourceBuilder res m id diff

Set the create method for the resource.

setRead :: (id -> m [res]) -> ResourceBuilder res m id diff

Set the read method for the resource.

setUpdate :: (id -> diff -> m Bool) -> ResourceBuilder res m id diff

Set the update method for the resource. The method must return a boolean, indicating whether anything was updated.

setDelete :: (id -> m Bool) -> ResourceBuilder res m id diff

Set the delete method for the resource. The method must return a boolean, indicating whether anything was deleted.

setToDiff :: (res -> diff) -> ResourceBuilder res m id diff

Sets the conversion function from resource to diff value.

setFromParams :: (Params -> Maybe id) -> ResourceBuilder res m id diff

Sets the URL query string parser.

setPutAction :: PutAction -> ResourceBuilder res m id diff

Sets a specific action to take when a PUT method is received. If not set, this defaults to trying to update and then creating if that fails.

data PutAction

Indicates which action that a PUT request should take for a resource.

Constructors

Create

Always create

Update

Always update

Instances

Eq PutAction

Show PutAction

Request parsing

class FromRequest id where

Instances of this class can be parsed from the remaining path information at the current route, and potentially also the URL parameters.

Methods

fromPath :: ByteString -> Maybe id

Parse a value from the remaining path information. A value of Nothing indicates that the parse failed.

Instances

FromRequest Int

FromRequest ()

FromRequest a => FromRequest [a]

FromRequest a => FromRequest (Maybe a)

FromRequest (CI String)

FromRequest (CI ByteString)

FromRequest (CI ByteString)

FromRequest (CI Text)

FromRequest a => FromRequest (Either a b)

(FromRequest a, FromRequest b) => FromRequest (a, b)

(FromRequest a, FromRequest b, FromRequest c) => FromRequest (a, b, c)

(FromRequest a, FromRequest b, FromRequest c, FromRequest d) => FromRequest (a, b, c, d)

parseRead :: Read a => ByteString -> Maybe a

A convenient helper function that wraps a read failure into Nothing instead of throwing an error.

type Params = Map ByteString [ByteString]

A type alias for the HTTP parameters mapping. Each parameter key maps to a list of ByteString values; if a parameter is specified multiple times (e.g.: "GET /foo?param=bar1&param=bar2"), looking up "param" in the mapping will give you ["bar1", "bar2"].

Media

data Media res m diff int

A grouping of mediatypes and their associated renderers and parsers. You can use the standard instances defined below, or define your own.

newMedia :: (Intermediate int, MonadSnap m) => [MediaType] -> [MediaType] -> Media res m diff int

Construct a new media grouping with the given response and request mediatypes.

newIntermediateMedia :: (int -> m ByteString) -> (ByteString -> m (Maybe int)) -> [MediaType] -> [MediaType] -> Media res m diff int

Construct a new media grouping with an intermediate type between the resource and the rendered form.

newRequestMedia :: (ByteString -> m (Maybe int)) -> [MediaType] -> Media res m diff int

Construct a new media grouping with request mediatypes only.

newResponseMedia :: (int -> m ByteString) -> [MediaType] -> Media res m diff int

Construct a new media grouping with response mediatypes only.

type MediaSetter res m diff int f a = Setter (Media res m diff int) (Media res m diff int) (f a) a

A Setter for defining properties of a media grouping.

fromResource :: MediaSetter res m diff int Maybe (res -> m int)

Set the resource renderer.

toResource :: MediaSetter res m diff int Maybe (int -> m (Maybe res))

Set the resource parser.

toDiff :: MediaSetter res m diff int Maybe (int -> m (Maybe diff))

Set the diff parser.

toEither :: MediaSetter res m res int Both (int -> m (Maybe res))

Set the resource and diff parser at the same time.

fromResourceList :: MediaSetter res m diff int Maybe ([res] -> m int)

Set the resource list renderer.

toResourceList :: MediaSetter res m diff int Maybe (int -> m (Maybe [res]))

Set the resource list parser.

Common media instances

json :: Monad m => Media res m diff Value

Outputs JSON in UTF-8 and parses JSON agnostic of character set.

jsonFromInstances :: (Monad m, ToJSON res, FromJSON res, FromJSON diff) => Media res m diff Value

Outputs JSON in UTF-8 and parses JSON agnostic of character set. Uses the type class instances to automatically set the media methods.

xml :: Monad m => Media res m diff Document

Outputs XML in UTF-8 and parses XML agnostic of character set.

xhtml :: MonadSnap m => Media res m diff ByteString

Supports both XHTML and HTML in UTF-8 as the output format only. Recommended over html if the output will be valid XHTML.

html :: MonadSnap m => Media res m diff ByteString

Supports HTML in UTF-8 as the output format only. Use xhtml if the output is guaranteed to be well formed.

form :: MonadSnap m => Media res m diff Params

Supports URL-encoded web forms as the input format only.

multipart :: MonadSnap m => Media res m diff ByteString

Supports multipart web forms as the input format only.

Config

data ResourceConfig m

Configuration data.

Constructors

ResourceConfig

Fields

readLimit :: Maybe Int

The maximum number of members to retrieve from a collection in a single request.

maxRequestBodySize :: Int64

Maximum size of request bodies allowed when receiving resources.

onHeaderFailure :: m ()

Action to run if the request header parsing fails.

onPathFailure :: m ()

Action to run if the resource path parsing fails.

onQueryFailure :: m ()

Action to run if the URL query string parsing fails.

onLookupFailure :: m ()

Action to run if the requested resource cannot be found.

onMethodFailure :: m ()

Action to run an invalid method is requested on a resource.

onAcceptFailure :: m ()

Action to run if the response media type is not supported.

onContentTypeFailure :: m ()

Action to run if the request media type is not supported.

onContentParseFailure :: m ()

Action to run if the request body parse fails.

defaultConfig :: MonadSnap m => Int64 -> ResourceConfig m

The default configuration settings. Requires a value for the maximum size of a request body.

 defaultConfig mrbs = ResourceConfig
     { readLimit = Nothing
     , maxRequestBodySize = mrbs
     , on*Failure = write "reason"
     }

class HasResourceConfig b where

The type class for an implementing Snaplet.

Methods

resourceLens :: SnapletLens (Snaplet b) (ResourceConfig (Handler b b))

Retrieve the configuration from the Snaplet monad.

type Resources b = ResourceConfig (Handler b b)

Convenience alias of ResourceConfig.

resourceInit :: ResourceConfig (Handler b b) -> SnapletInit b (Resources b)

Initialize the resource snaplet with the given configuration.

resourceInitDefault :: Int64 -> SnapletInit b (Resources b)

Initialize the resource snaplet with the default configuration.