rest-core-0.39: Rest API library.

Safe HaskellNone
LanguageHaskell98

Rest.Api

Contents

Description

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'.

Synopsis

Api data types.

data Api m where #

An API can be versioned or unversioned. A versioned API is a set of versioned routers. An unversioned API is just a single router.

Constructors

Unversioned :: Some1 (Router m) -> Api m 
Versioned :: VersionSet m -> Api m 

type VersionSet m = [(Version, Some1 (Router m))] #

A version set 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

Instances

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

Smart constructor for Version.

latest :: VersionSet 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 -> VersionSet 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 -> VersionSet 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.