Rest.Api

This module allows you to combine Resources into an Api. This can then be served using 'rest-happstack' or 'rest-snap', or used to generate clients or documentation using 'rest-gen'.

Api data types.

type Api m = [(Version, Some1 (Router m))]

An API is a list of versioned routers.

data Router m s where

A Router is a Resource and a list of subresources.

Constructors

Embed :: Resource m s sid mid aid -> [Some1 (Router s)] -> Router m s

data Some1 f where

An existential where the second argument has kind (* -> *).

Constructors

Some1 :: f (a :: * -> *) -> Some1 f

Defining routes.

route :: Monad s => Resource m s sid mid aid -> Router m s

Convenience constructor constructing a route without any subresource.

compose :: Router m s -> Router s t -> Router m s

Add the second router as a subresource to the first.

(-/) :: Router m s -> Router s t -> Router m s infixl 4

Operators with the right fixities to allow you to define routes without using parentheses. Start with the shortest near the root.

(--/) :: Router m s -> Router s t -> Router m s infixl 5

Operators with the right fixities to allow you to define routes without using parentheses. Start with the shortest near the root.

(---/) :: Router m s -> Router s t -> Router m s infixl 6

Operators with the right fixities to allow you to define routes without using parentheses. Start with the shortest near the root.

(----/) :: Router m s -> Router s t -> Router m s infixl 7

Operators with the right fixities to allow you to define routes without using parentheses. Start with the shortest near the root.

(-----/) :: Router m s -> Router s t -> Router m s infixl 8

Operators with the right fixities to allow you to define routes without using parentheses. Start with the shortest near the root.

(------/) :: Router m s -> Router s t -> Router m s infixl 9

Operators with the right fixities to allow you to define routes without using parentheses. Start with the shortest near the root.

root :: (Applicative m, Monad m) => Router m m

An empty router to use as the root for your API.

Api versioning.

data Version

An API version has three parts. The first is two are used for API breaking changes, the last for non-API breaking changes.

Constructors

Version

Fields

full :: Int

major :: Int

minor :: Maybe Int

Instances

Eq Version

Ord Version

Show Version

mkVersion :: Int -> Int -> Int -> Version

Smart constructor for Version.

latest :: Api m -> Maybe (Version, Some1 (Router m))

Get the latest version of an API.

parseVersion :: String -> Maybe Version

Parse a String as a Version. The string should contain two or three numbers separated by dots, e.g. 1.12.3.

lookupVersion :: String -> Api m -> Maybe (Some1 (Router m))

Look up a version in an API. The string can either be a valid version according to parseVersion, or "latest".

lookupVersion' :: Version -> Api m -> Maybe (Some1 (Router m))

Look up a version in the API.

withVersion :: String -> Api m -> r -> (Version -> Some1 (Router m) -> r) -> r

Given a version string, an API and a fallback, do the following:

• Parse the version number or "latest".
• Look up this version.
• If ok, run the given function on it.
• If not parsed or found, return the fallback.