Rename HTTP API field names and add warnings

sourceHtml → content
resultHtml → content

#18

CHANGES.md

@@ -32,13 +32,22 @@ To be released.
 
     The below HTTP APIs changed:
 
+     -  Added a mandatory field `"content"` to requests.
+     -  Deprecated the `"sourceHtml"` field of requests in favour of the new
+        `"content"` field.
      -  Added an optional field `"contentType"` with the default value
         `"text/html"` to requests.
-     -  Removed `"xhtml"` field in favour of new `"contentType"` field
-        from requests.
+     -  Deprecated the `"xhtml"` field of requests in favour of the new
+        `"contentType"` field.  The legacy field will be gone in the next
+        minor release.
         In order to use XHTML mode, configure `"contentType"` field with
         `"application/xhtml+xml"`.
+     -  Added `"content"` field to responses.
+     -  Deprecated the `"resultHtml"` field of responses in favour of the new
+        `"content"` field.  The legacy field is not provided for non-HTML
+        types, and will be gone in the next minor release.
      -  Added `"contentType"` field to responses.
+     -  Added `"warnings"` field to responses.
 
  -  Added `Text.Seonbi.Html.Lang` module.
 

app/seonbi-api.hs

@@ -7,6 +7,7 @@ module Main (main) where
 
 import Control.Concurrent (threadDelay)
 import Control.Monad
+import Data.Maybe (catMaybes)
 import Data.String
 import Data.Version
 import GHC.Exts (IsList (..))
@@ -29,15 +30,38 @@ import Text.Seonbi.Facade
 import Text.Seonbi.Trie as Trie
 
 data Input = Input
-    { sourceHtml :: Text
+    { source :: Text
     , configuration :: Configuration IO ()
+    , warnings :: [Text]
     } deriving (Show)
 
 instance FromJSON Input where
     parseJSON = withObject "Input" $ \ v -> do
-        sourceHtml' <- v .: "sourceHtml"
+        sourceMaybe <- v .:? "content"
+        (source', w1) <- case sourceMaybe of
+            Just s -> return (s, Nothing)
+            Nothing -> do
+                sourceHtml' <- v .:? "sourceHtml"
+                case sourceHtml' of
+                    Just h -> return
+                        ( h
+                        , Just $ "key \"sourceHtml\" is deprecated in " <>
+                                 "favour of \"content\""
+                        )
+                    Nothing -> fail "key \"content\" not present"
         preset <- v .:? "preset"
-        contentType' <- v .:? "contentType" .!= "text/html"
+        contentTypeMaybe <- v .:? "contentType"
+        (contentType', w2) <- case contentTypeMaybe of
+            Just t -> return (t, Nothing)
+            Nothing -> do
+                xhtml <- v .:? "xhtml"
+                case xhtml of
+                    Just x -> return
+                        ( if x then "application/xhtml+xml" else "text/html"
+                        , Just $ "key \"xhtml\" is deprecated in favour of " <>
+                                 "\"contentType\""
+                        )
+                    Nothing -> return ("text/html", Nothing)
         config <- case preset of
             Just locale ->
                 let presets' = presets :: M.Map Text (Configuration IO ())
@@ -70,7 +94,11 @@ instance FromJSON Input where
                     , stop = stop'
                     , hanja = hanja'
                     }
-        return $ Input sourceHtml' $ config { contentType = contentType' }
+        return $ Input
+            { source = source'
+            , configuration = config { contentType = contentType' }
+            , warnings = catMaybes [w1, w2]
+            }
 
 instance FromJSON ContentType where
     parseJSON = withText "ContentType" $ \ t ->
@@ -129,13 +157,28 @@ app AppOptions { allowOrigin, debugDelayMs } request respond =
             inputJson <- lazyRequestBody request
             threadDelay (debugDelayMs * 1000)
             case eitherDecode' inputJson of
-                Right (Input source config) -> do
+                Right (Input source config warnings) -> do
                     result <- transformHtmlText config source
-                    respond' status200 $ object
+                    let type' = contentType config
+                    let warningComments =
+                            if Prelude.null warnings
+                            then Data.Text.empty
+                            else Data.Text.concat
+                                [ "<!--\n"
+                                , Data.Text.intercalate "\n" warnings
+                                , "\n-->"
+                                ]
+                    respond' status200 $ object $
                         [ "success" .= Bool True
-                        , "resultHtml" .= String result
-                        , "contentType" .= String
-                            (contentTypeText $ contentType config)
+                        , "content" .= String result
+                        , "warnings" .= Array
+                            (GHC.Exts.fromList $ String <$> warnings)
+                        , "contentType" .= String (contentTypeText type')
+                        ]
+                        ++
+                        [ "resultHtml" .= String (warningComments <> result)
+                        | type' == "text/html" ||
+                          type' == "application/xhtml+xml"
                         ]
                 Left msg -> respond' status400 $ object
                     [ "success" .= Bool False

demo/src/Demo.elm

@@ -118,6 +118,7 @@ type alias Source =
 type alias Result_ =
     { content : String
     , contentType : ContentType
+    , warnings : List String
     }
 
 
@@ -271,7 +272,12 @@ init _ =
                 }
             , loading = True
             , lastTransformation = Nothing
-            , result = Just { content = "", contentType = Html }
+            , result =
+                Just
+                    { content = ""
+                    , contentType = Html
+                    , warnings = []
+                    }
             , sourceTabState = Tab.initialState
             , resultTabState = Tab.initialState
             , customDictionaryVisibility = Modal.hidden
@@ -301,7 +307,7 @@ makeInput source =
     ( apiServerUrl
     , Json.Encode.object <|
         List.append
-            [ ( "sourceHtml"
+            [ ( "content"
               , Json.Encode.string <|
                     if source.contentType == PlainText then
                         Maybe.withDefault "" source.text
@@ -441,12 +447,13 @@ transform source =
         ( url_, input ) =
             makeInput source
 
-        mkResult contentType content =
+        mkResult contentType content warnings =
             case parseContentType contentType of
                 Just t ->
                     Just
                         { contentType = t
                         , content = content
+                        , warnings = warnings
                         }
 
                 Nothing ->
@@ -457,10 +464,13 @@ transform source =
         , body = Http.jsonBody input
         , expect =
             Http.expectJson (EndTransform source) <|
-                Json.Decode.map2
+                Json.Decode.map3
                     mkResult
                     (Json.Decode.field "contentType" Json.Decode.string)
-                    (Json.Decode.field "resultHtml" Json.Decode.string)
+                    (Json.Decode.field "content" Json.Decode.string)
+                    (Json.Decode.field "warnings" <|
+                        Json.Decode.list Json.Decode.string
+                    )
         }
 
 
@@ -480,8 +490,8 @@ update msg model =
                         Nothing ->
                             Just
                                 { content = ""
-                                , contentType =
-                                    model.source.contentType
+                                , contentType = model.source.contentType
+                                , warnings = []
                                 }
 
                         r ->