Skip to content
Tutorials Center
My learning

Topics

Lesson 47 of 57 ยท Real-world Haskell

JSON and Web Services

Encode and decode JSON in Haskell with aeson and generics, then see how Scotty and servant build web services and how wreq calls other APIs.

Most real programs talk to the outside world through JSON over HTTP. Haskell's strengths show up here: the type of a value tells you exactly what JSON it produces, decoding is checked against that type, and a malformed request becomes a value you handle rather than a crash.

This lesson tours the standard tools: aeson for JSON, Scotty and servant for serving, and wreq or http-client for calling other services. It assumes records, Maybe and Either, type classes and Cabal packages.

Real Haskell and its libraries are not installed on this site, so every Haskell block is read-only. The two runnable examples are JavaScript stand-ins that show the design, not the libraries.

JSON as a type

aeson represents a JSON document with a plain algebraic data type, much like the one you will write yourself in the JSON parser project:

HASKELL
data Value
  = Object (KeyMap Value)
  | Array  (Vector Value)
  | String Text
  | Number Scientific
  | Bool   Bool
  | Null

Two type classes convert your own types to and from Value:

HASKELL
class ToJSON a   where toJSON    :: a -> Value
class FromJSON a where parseJSON :: Value -> Parser a

encode turns anything with a ToJSON instance into bytes, and decode (or the more informative eitherDecode) goes back:

HASKELL
encode       :: ToJSON a   => a -> ByteString
eitherDecode :: FromJSON a => ByteString -> Either String a

eitherDecode returns Left with a message such as key "age" not found, which is far better than decode's bare Nothing.

Instances by hand and by Generic

You can write the instances yourself:

HASKELL
# LANGUAGE OverloadedStrings #
import Data.Aeson

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

instance ToJSON User where
  toJSON (User n a) = object ["name" .= n, "age" .= a]

instance FromJSON User where
  parseJSON = withObject "User" $ \o ->
    User <$> o .: "name" <*> o .: "age"

.= builds a key-value pair, .: reads a required key, and .:? reads an optional one into a Maybe. The decoder is an applicative over the fields: if any field is missing or has the wrong type, the whole parse fails with a message.

For ordinary records you can skip all that. With the DeriveGeneric and DeriveAnyClass extensions (see GHC Extensions), the compiler derives both instances from the type's shape:

HASKELL
# LANGUAGE DeriveGeneric, DeriveAnyClass #
import GHC.Generics (Generic)

data User = User { name :: Text, age :: Int }
  deriving (Show, Generic, ToJSON, FromJSON)

By default the JSON keys equal the field names. Real code usually has prefixed fields such as userName, so you pass options to rename them:

HASKELL
instance ToJSON User where
  toJSON = genericToJSON defaultOptions { fieldLabelModifier = map toLower . drop 4 }

Sum types become tagged objects, so a Shape with Circle and Square constructors encodes with a "tag" key and a "contents" key unless you configure sumEncoding.

JSON round trip

Haskell value A typed record.
JSON text What goes over the wire.
Typed again Decoding checks the shape.
1 / 2

A runnable stand-in for encoding and decoding

JavaScript has no static types, so this stand-in uses a small schema object that plays the role of the type: a decoder either returns a value or an error message, like eitherDecode. Real aeson derives that behaviour from your Haskell types.

JS Decoding JSON against a schema

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Serving JSON with Scotty

Scotty is a small web framework inspired by Ruby's Sinatra. You describe routes as a list of actions in the ScottyM monad, and each handler is an ActionM that reads the request and writes a response:

HASKELL
# LANGUAGE OverloadedStrings #
import Web.Scotty

main :: IO ()
main = scotty 3000 $ do
  get "/hello/:who" $ do
    who <- pathParam "who"
    json (object ["greeting" .= ("Hello, " <> who :: Text)])

  post "/users" $ do
    user <- jsonData :: ActionM User     -- 400 if the body does not decode
    json user                            -- echo it back as JSON

jsonData uses your FromJSON instance, so the same type you wrote once validates incoming bodies and shapes outgoing ones. Scotty is perfect for prototypes and small services.

Types as API descriptions: servant

servant takes a different approach: you describe the whole API as a type, and the library derives the server, client functions and even documentation from it:

HASKELL
# LANGUAGE DataKinds, TypeOperators #
import Servant

type UserAPI =
       "users" :> Get '[JSON] [User]
  :<|> "users" :> Capture "id" Int :> Get '[JSON] User
  :<|> "users" :> ReqBody '[JSON] User :> Post '[JSON] NoContent

server :: Server UserAPI
server = listUsers :<|> getUser :<|> createUser
  where
    listUsers  = pure allUsers
    getUser i  = maybe (throwError err404) pure (lookupUser i)
    createUser u = saveUser u >> pure NoContent

main :: IO ()
main = run 8080 (serve (Proxy :: Proxy UserAPI) server)

If your handlers do not match the type, the program does not compile. Add a route to the type and the compiler tells you the server is missing a handler. The price is more advanced types (these are the type-level features from the previous chapter) and longer error messages.

A runnable stand-in for routing

This stand-in models the same idea as both frameworks: a route table, handlers that return a response value, and a pure function handle from request to response, so it can be tested without a socket.

JS A pure router

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Calling other services

For the client side, wreq offers a friendly API on top of http-client:

HASKELL
import Network.Wreq
import Control.Lens ((^.))
import Data.Aeson (eitherDecode)

main :: IO ()
main = do
  r <- get "https://api.example.com/users/1"
  print (r ^. responseStatus . statusCode)
  case eitherDecode (r ^. responseBody) :: Either String User of
    Left msg   -> putStrLn ("bad response: " ++ msg)
    Right user -> print user

wreq uses lenses to read parts of the response. http-client with http-client-tls is lower level and has no lens dependency; req is another popular choice with strong typing for request bodies. Servant can also derive a client from the same UserAPI type, so server and client cannot drift apart.

Network calls fail: DNS, timeouts, non-200 statuses, bad JSON. Wrap them with the exception handling from Exceptions and Error Handling, set timeouts, and never trust a response body without eitherDecode.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which function returns an error message when JSON does not match your type?

    eitherDecode returns Either String a, so a Left carries the reason. decode only gives Maybe.
  2. 2. What does deriving Generic with ToJSON and FromJSON give you?

    DeriveGeneric and DeriveAnyClass let aeson build both instances from the constructor and field names.
  3. 3. What is distinctive about servant?

    A servant API is a type; handlers must match it, and clients and docs can be generated from it.
  4. 4. Which operator reads a required field in a hand-written FromJSON instance?

    .: reads a required key from an object; .= builds a pair when encoding.

Summary

  • aeson models JSON as the Value type; ToJSON and FromJSON convert your types.
  • Prefer eitherDecode for useful error messages; write instances by hand or derive them with Generic and options.
  • Scotty is a light, route-based framework; servant describes the API as a type and derives server, client and docs.
  • wreq, req and http-client call other services; handle failures and validate bodies.
  • Keep request handling a pure function where you can, so it is easy to test.

Next: Project: Expression Calculator.