JSON conveniences

Since JSON is such a commonly used data format in web applications today, we have some built-in helper functions for providing JSON representations. These are built off of the wonderful aeson library, so let’s start off with a quick explanation of how that library works.

aeson has a core datatype, Value, which represents any valid JSON value. It also provides two typeclasses- ToJSON and FromJSON- to automate marshaling to and from JSON values, respectively. For our purposes, we’re currently interested in ToJSON. Let’s look at a quick example of creating a ToJSON instance for our ever-recurring Person data type examples.

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE RecordWildCards   #-}
import           Data.Aeson
import qualified Data.ByteString.Lazy.Char8 as L
import           Data.Text                  (Text)

data Person = Person
    { name :: Text
    , age  :: Int
    }

instance ToJSON Person where
    toJSON Person {..} = object
        [ "name" .= name
        , "age"  .= age
        ]

main :: IO ()
main = L.putStrLn $ encode $ Person "Michael" 28

I won’t go into further detail on aeson, as the Haddock documentation already provides a great introduction to the library. What I’ve described so far is enough to understand our convenience functions.

Let’s suppose that you have such a Person datatype, with a corresponding value, and you’d like to use it as the representation for your current page. For that, you can use the returnJson function.

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes       #-}
{-# LANGUAGE RecordWildCards   #-}
{-# LANGUAGE TemplateHaskell   #-}
{-# LANGUAGE TypeFamilies      #-}
import           Data.Text (Text)
import           Yesod

data Person = Person
    { name :: Text
    , age  :: Int
    }

instance ToJSON Person where
    toJSON Person {..} = object
        [ "name" .= name
        , "age"  .= age
        ]

data App = App

mkYesod "App" [parseRoutes|
/ HomeR GET
|]

instance Yesod App

getHomeR :: Handler Value
getHomeR = returnJson $ Person "Michael" 28

main :: IO ()
main = warp 3000 App

returnJson is actually a trivial function; it is implemented as return . toJSON. However, it makes things just a bit more convenient. Similarly, if you would like to provide a JSON value as a representation inside a selectRep, you can use provideJson.

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes       #-}
{-# LANGUAGE RecordWildCards   #-}
{-# LANGUAGE TemplateHaskell   #-}
{-# LANGUAGE TypeFamilies      #-}
import           Data.Text (Text)
import           Yesod

data Person = Person
    { name :: Text
    , age  :: Int
    }

instance ToJSON Person where
    toJSON Person {..} = object
        [ "name" .= name
        , "age"  .= age
        ]

data App = App

mkYesod "App" [parseRoutes|
/ HomeR GET
|]

instance Yesod App

getHomeR :: Handler TypedContent
getHomeR = selectRep $ do
    provideRep $ return
        [shamlet|
            <p>Hello, my name is #{name} and I am #{age} years old.
        |]
    provideJson person
  where
    person@Person {..} = Person "Michael" 28

main :: IO ()
main = warp 3000 App

provideJson is similarly trivial, in this case provideRep . return . toEncoding.

New datatypes

Let’s say I’ve come up with some new data format based on using Haskell’s Show instance; I’ll call it “Haskell Show”, and give it a mime type of text/haskell-show. And let’s say that I decide to include this representation from my web app. How do I do it? For a first attempt, let’s use the TypedContent datatype directly.

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes       #-}
{-# LANGUAGE TemplateHaskell   #-}
{-# LANGUAGE TypeFamilies      #-}
import           Data.Text (Text)
import           Yesod

data Person = Person
    { name :: Text
    , age  :: Int
    }
    deriving Show

data App = App

mkYesod "App" [parseRoutes|
/ HomeR GET
|]

instance Yesod App

mimeType :: ContentType
mimeType = "text/haskell-show"

getHomeR :: Handler TypedContent
getHomeR =
    return $ TypedContent mimeType $ toContent $ show person
  where
    person = Person "Michael" 28

main :: IO ()
main = warp 3000 App

There are a few important things to note here.

• We’ve used the toContent function. This is a typeclass function that can convert a number of data types to raw data ready to be sent over the wire. In this case, we’ve used the instance for String, which uses UTF8 encoding. Other common data types with instances are Text, ByteString, Html, and aeson’s Value.

• We’re using the TypedContent constructor directly. It takes two arguments: a mime type, and the raw content. Note that ContentType is simply a type alias for a strict ByteString.

That’s all well and good, but it bothers me that the type signature for getHomeR is so uninformative. Also, the implementation of getHomeR looks pretty boilerplate. I’d rather just have a datatype representing "Haskell Show" data, and provide some simple means of creating such values. Let’s try this on for size:

{-# LANGUAGE ExistentialQuantification #-}
{-# LANGUAGE OverloadedStrings         #-}
{-# LANGUAGE QuasiQuotes               #-}
{-# LANGUAGE TemplateHaskell           #-}
{-# LANGUAGE TypeFamilies              #-}
import           Data.Text (Text)
import           Yesod

data Person = Person
    { name :: Text
    , age  :: Int
    }
    deriving Show

data App = App

mkYesod "App" [parseRoutes|
/ HomeR GET
|]

instance Yesod App

mimeType :: ContentType
mimeType = "text/haskell-show"

data HaskellShow = forall a. Show a => HaskellShow a

instance ToContent HaskellShow where
    toContent (HaskellShow x) = toContent $ show x
instance ToTypedContent HaskellShow where
    toTypedContent = TypedContent mimeType . toContent

getHomeR :: Handler HaskellShow
getHomeR =
    return $ HaskellShow person
  where
    person = Person "Michael" 28

main :: IO ()
main = warp 3000 App

The magic here lies in two typeclasses. As we mentioned before, ToContent tells how to convert a value into a raw response. In our case, we would like to show the original value to get a String, and then convert that String into the raw content. Often times, instances of ToContent will build on each other in this way.

ToTypedContent is used internally by Yesod, and is called on the result of all handler functions. As you can see, the implementation is fairly trivial, simply stating the mime type and then calling out to toContent.

Finally, let’s make this a bit more complicated, and get this to play well with selectRep.

{-# LANGUAGE ExistentialQuantification #-}
{-# LANGUAGE OverloadedStrings         #-}
{-# LANGUAGE QuasiQuotes               #-}
{-# LANGUAGE RecordWildCards           #-}
{-# LANGUAGE TemplateHaskell           #-}
{-# LANGUAGE TypeFamilies              #-}
import           Data.Text (Text)
import           Yesod

data Person = Person
    { name :: Text
    , age  :: Int
    }
    deriving Show

instance ToJSON Person where
    toJSON Person {..} = object
        [ "name" .= name
        , "age"  .= age
        ]

data App = App

mkYesod "App" [parseRoutes|
/ HomeR GET
|]

instance Yesod App

mimeType :: ContentType
mimeType = "text/haskell-show"

data HaskellShow = forall a. Show a => HaskellShow a

instance ToContent HaskellShow where
    toContent (HaskellShow x) = toContent $ show x
instance ToTypedContent HaskellShow where
    toTypedContent = TypedContent mimeType . toContent
instance HasContentType HaskellShow where
    getContentType _ = mimeType

getHomeR :: Handler TypedContent
getHomeR = selectRep $ do
    provideRep $ return $ HaskellShow person
    provideJson person
  where
    person = Person "Michael" 28

main :: IO ()
main = warp 3000 App

The important addition here is the HasContentType instance. This may seem redundant, but it serves an important role. We need to be able to determine the mime type of a possible representation before creating that representation. ToTypedContent only works on a concrete value, and therefore can’t be used before creating the value. getContentType instead takes a proxy value, indicating the type without providing anything concrete.