Kuro's Blog: [haskell][yesod] TypedContentを利用してクライアントが要求するフォーマットでレスポンスを返す

Yesod Advent Calendar 2016の6日目の記事です。

RESTfulなAPIを提供する場合、クライアントの都合にあわせて、フォーマットを変えてレスポンスを返したいケースがあります。サーバー上で管理しているDBから、表現だけをHTML, JSON, XML, CSVなどに変更して返すイメージです。例えば、人物情報（名前、年齢、性別など）の一覧を返す際には以下のようなデータが返されることになります。

HTML

<table border>
  <tr>
    <th>name</th>    <th>sex</th>    <th>age</th>
  </tr>
  <tr>
    <td>Taro Yamada</td>    <td>Male</td>    <td>18</td>
  </tr>
  <tr>
    <td>Hanako Yamada</td>    <td>Female</td>    <td>25</td>
  </tr>
  <tr>
    <td>Ichiro Suzuki</td>    <td>Male</td>    <td>43</td>
  </tr>
</table>

JSON

 [
  {"name":"Taro Yamada", "sex":"Male", "age":18},
  {"name":"Hanako Yamada", "sex":"Female", "age":25},
  {"name":"Ichiro Suzuki", "sex":"Male", "age":43}
 ]

 Taro Yamada,Male,18
 Hanako Yamada,Female,25
 Ichiro Suzuki,Male,43

通常はフォーマット毎に別のURLを割り当てますが、Yesodでは1つのURLで複数フォーマットのレスポンスを返す実装が簡単にできます。
このエントリでは、http://localhost:3000/に対応する一つのハンドラの中でTypedContentを利用して複数のフォーマットを扱う方法を紹介します。クライアントが送信するリクエストに記載されるAcceptヘッダによって、サーバーの挙動を変えます。

準備：

まず、素のYesodのscaffolding siteを起動できる環境を作ります。stackが利用できる環境を前提にしています。

yesod-simpleを指定して空の"typedcontent"プロジェクトを生成

% stack new typedcontent yesod-simple

生成したプロジェクトディレクトリに移動し、依存ツールをビルド

% cd typedcontent
% stack build yesod-bin cabal-install

生成したtypedcontentプロジェクトをビルド

% stack build

develサーバーを起動

% stack exec -- yesod devel

http://localhost:3000/

基礎1：Home.hsを修正してHTMLを返すシンプルなハンドラを作ってみる

Handler/Home.hsに人物情報データ定義を追加

-- サーバー上で管理するデータ定義。
data Sex = Male | Female
    deriving (Show)
data Person = Person
    { name :: Text
    , age  :: Int
    , sex  :: Sex
    }
    deriving (Show)

-- サーバー上のサンプルデータ。3人分の情報を保持。
samplePersonList :: [Person]
samplePersonList = [ (Person "Taro Yamada" 18 Male)
                   , (Person "Hanako Yamada" 25 Female)
                   , (Person "Ichiro Suzuki" 41 Male) ]

Handler/Home.hsのgetHomeRの定義を更新

-- HTML tableフォーマットでレスポンスを生成。
toTableHtml :: Handler Html
toTableHtml = withUrlRenderer [hamlet|
             <table border>
                 <tr>                                                         
                   <th>name                                                   
                   <th>age                                                    
                   <th>sex                                                    
               $forall person <- samplePersonList                             
                 <tr>                                                         
                   <td>#{name person}                                         
                   <td>#{age person}                                          
                   <td>#{show $ sex person}                            
             |]

getHomeR :: Handler Html
getHomeR = toTableHtml

動作確認

% curl http://localhost:3000/

基礎2：クライアント要求に応じてHTMLとplain textのどちらかを返す

いよいよ、クライアントからの要求に応じて異なるフォーマットを返すよう、getHomeRを改変します。ここでは"text/html"が要求されている場合にはHTMLを、"text/plain"が要求されている場合にはshow関数の実行結果を返すようにします。

getHomeRの型をHandler HtmlからHandler TypedContentに変更し、"text/html"と"text/plain"に対応する

getHomeR :: Handler TypedContent
getHomeR = selectRep $ do
    provideRep $ toTableHtml
    provideRep $ return $ repPlain $ show samplePersonList

動作確認

% curl -H "Accept: text/plain" http://localhost:3000/
[Person {name = "Taro Yamada", age = 18, sex = Male},Person {name = "Hanako Yamada", age = 25, sex = Female},Person {name = "Ichiro Suzuki", age = 41, sex = Male}]
% curl -H "Accept: text/html" http://localhost:3000/
<table border><tr><th>name</th>
<th>age</th>
<th>sex</th>
...

% curl http://localhost:3000/?_accept=text/plain
[Person {name = "Taro Yamada", age = 18, sex = Male},Person {name = "Hanako Yamada", age = 25, sex = Female},Person {name = "Ichiro Suzuki", age = 41, sex = Male}]

provideRepをprovideRepTypeに置き換えてみる

getHomeR :: Handler TypedContent
getHomeR = selectRep $ do
    provideRep $ toTableHtml
--    provideRep $ return $ repPlain $ show samplePersonList
    provideRepType "text/plain" (return $ show samplePersonList)

応用：JSON, CSVフォーマットをサポートする

ここまでの手順を応用して、CSV及びJSONフォーマットを返すようにgetHomeRを拡張します。

provideRepTypeを利用してCSVフォーマットを返す実装を追加

-- CSVフォーマットのレスポンスを生成する。
class ToCSV a where
  toCsv :: a -> Text
instance ToCSV Person where
  toCsv p = (name p) 
           ++ ("," :: Text) 
           ++ (pack $ show $ age p) 
           ++ ("," :: Text) 
           ++ (pack $ show $ sex p) 
           ++ ("\n" :: Text)
instance (ToCSV a) => ToCSV [a] where
  toCsv [] = ""
  toCsv (x:xs) = (toCsv x) ++ (toCsv xs)

getHomeR :: Handler TypedContent
getHomeR = selectRep $ do
    provideRep $ toTableHtml
    provideRep $ return $ repPlain $ show samplePersonList
    provideRepType "text/csv" (return $ toCsv samplePersonList) -- 追加！

動作確認

% curl -H "Accept: text/csv" http://localhost:3000/ 
Taro Yamada,18,Male
Hanako Yamada,25,Female
Ichiro Suzuki,41,Male

ついでにJSONもサポート

{-# LANGUAGE DeriveGeneric #-}

-- toJSONを自動導出。DeriveGeneric言語拡張が必要。
instance ToJSON Sex 
instance ToJSON Person 

getHomeR :: Handler TypedContent
getHomeR = selectRep $ do
    provideRep $ toTableHtml
    provideRep $ return $ repPlain $ show samplePersonList
    provideRepType "text/csv" (return $ toCsv samplePersonList) 
    provideJson $ samplePersonList -- 追加！

動作確認

% curl -H "Accept: application/json" http://localhost:3000/ 
[{"age":18,"name":"Taro Yamada","sex":"Male"},{"age":25,"name":"Hanako Yamada","sex":"Female"},{"age":41,"name":"Ichiro Suzuki","sex":"Male"}]

まとめ：

TypedContentを利用して一つのURLからHTML, PlainText, CSV, JSONフォーマットのデータを返す方法を説明しました。ハンドラを実装する上で、selectRep/provideRep/provideRepTypeをどう使えばよいか、YesodフレームワークがContentTypeの判定にHasContentTypeを用いている、といったキモになる情報をまとめています。
このエントリで利用したコードは以下のgithubリポジトリにコミットしてあるので、参考にしてください。
https://github.com/kurokawh/work_haskell/tree/master/yesodweb/typedcontent