Add Named Servant API routes

This big commit adds a separate module hierarchy for Servant named
routes (see https://www.tweag.io/blog/2022-02-24-named-routes/ ) which
will make working with servant endpoints more pleasant (especially when
it comes to emitted errors).

This still doesn't do anything to wire the routes to the concrete
handlers.

gargantext.cabal

@@ -134,9 +134,29 @@ library
       Gargantext.API.Node.File
       Gargantext.API.Node.Share
       Gargantext.API.Node.ShareURL
+      Gargantext.API.Node.Types
       Gargantext.API.Node.Update
       Gargantext.API.Prelude
       Gargantext.API.Routes
+      Gargantext.API.Routes.Named
+      Gargantext.API.Routes.Named.Contact
+      Gargantext.API.Routes.Named.Context
+      Gargantext.API.Routes.Named.Corpus
+      Gargantext.API.Routes.Named.Count
+      Gargantext.API.Routes.Named.Document
+      Gargantext.API.Routes.Named.File
+      Gargantext.API.Routes.Named.FrameCalc
+      Gargantext.API.Routes.Named.List
+      Gargantext.API.Routes.Named.Metrics
+      Gargantext.API.Routes.Named.Node
+      Gargantext.API.Routes.Named.Private
+      Gargantext.API.Routes.Named.Public
+      Gargantext.API.Routes.Named.Search
+      Gargantext.API.Routes.Named.Share
+      Gargantext.API.Routes.Named.Table
+      Gargantext.API.Routes.Named.Tree
+      Gargantext.API.Routes.Named.Viz
+      Gargantext.API.Routes.Types
       Gargantext.Core
       Gargantext.Core.Mail.Types
       Gargantext.Core.Methods.Similarities
@@ -281,7 +301,6 @@ library
       Gargantext.API.Node.FrameCalcUpload
       Gargantext.API.Node.Get
       Gargantext.API.Node.New
-      Gargantext.API.Node.Types
       Gargantext.API.Public
       Gargantext.API.Search
       Gargantext.API.Server

src/Gargantext/API/Count.hs

@@ -16,8 +16,22 @@ Count API part of Gargantext.
 {-# LANGUAGE TypeOperators      #-}
 {-# LANGUAGE DeriveAnyClass     #-}
 
-module Gargantext.API.Count
-      where
+module Gargantext.API.Count (
+    CountAPI
+  , Scraper(..)
+  , QueryBool(..)
+  , Query(..)
+  , Message(..)
+  , Code
+  , Error
+  , Errors
+  , Counts(..)
+  , Count(..)
+
+  -- * functions
+  , count
+  , scrapers
+  ) where
 
 import Data.Swagger ( ToSchema(..), genericDeclareNamedSchema )
 import Data.Text (pack)

src/Gargantext/API/Node/Corpus/Export.hs

+{-# LANGUAGE TypeOperators #-}
 {-|
 Module      : Gargantext.API.Node.Corpus.Export
 Description : Corpus export
@@ -41,7 +42,14 @@ import Gargantext.Database.Query.Table.NodeContext (selectDocNodes)
 import Gargantext.Database.Schema.Context (_context_id)
 import Gargantext.Prelude hiding (hash)
 import Gargantext.Prelude.Crypto.Hash (hash)
-import Servant (Headers, Header, addHeader)
+import Servant (Headers, Header, addHeader, Summary, (:>), JSON, Get, QueryParam)
+
+--------------------------------------------------
+type API = Summary "Corpus Export"
+            :> "export"
+            :> QueryParam "listId"     ListId
+            :> QueryParam "ngramsType" NgramsType
+            :> Get '[JSON] (Headers '[Servant.Header "Content-Disposition" Text] Corpus)
 
 --------------------------------------------------
 -- | Hashes are ordered by Set

src/Gargantext/API/Node/Corpus/Export/Types.hs

@@ -18,8 +18,7 @@ import Data.Swagger ( ToSchema(..), genericDeclareNamedSchema, ToParamSchema(..)
 import Data.Text (Text)
 import GHC.Generics (Generic)
 import Gargantext.API.Node.Document.Export.Types qualified as DocumentExport
-import Gargantext.Core.Text.Ngrams (NgramsType(..))
-import Gargantext.Core.Types ( ListId, TODO )
+import Gargantext.Core.Types ( TODO )
 import Gargantext.Core.Utils.Prefix (unPrefix, unPrefixSwagger)
 import Servant
 
@@ -37,11 +36,4 @@ instance ToSchema Corpus where
 -------
 instance ToParamSchema Corpus where
   toParamSchema _ = toParamSchema (Proxy :: Proxy TODO)
---------------------------------------------------
-type API = Summary "Corpus Export"
-            :> "export"
-            :> QueryParam "listId"     ListId
-            :> QueryParam "ngramsType" NgramsType
-            :> Get '[JSON] (Headers '[Servant.Header "Content-Disposition" Text] Corpus)
-
 $(deriveJSON (unPrefix "_c_") ''Corpus)

src/Gargantext/API/Node/Corpus/New.hs

@@ -22,10 +22,9 @@ module Gargantext.API.Node.Corpus.New
 
 import Conduit
 import Control.Lens ( view, non )
-import Data.Aeson ( genericParseJSON, genericToJSON )
 import Data.ByteString.Base64 qualified as BSB64
 import Data.Conduit.Internal (zipSources)
-import Data.Swagger ( ToSchema(..), genericDeclareNamedSchema )
+import Data.Swagger ( ToSchema(..) )
 import Data.Text qualified as T
 import Data.Text.Encoding qualified as TE
 import EPO.API.Client.Types qualified as EPO
@@ -34,17 +33,16 @@ import Gargantext.API.Admin.Types (HasSettings)
 import Gargantext.API.Ngrams (commitStatePatch, Versioned(..))
 import Gargantext.API.Node.Corpus.New.Types ( FileFormat(..), FileType(..) )
 import Gargantext.API.Node.Corpus.Searx ( triggerSearxSearch )
-import Gargantext.API.Node.Corpus.Types ( Database, Datafield(Web), database2origin )
+import Gargantext.API.Node.Corpus.Types ( Datafield(Web), database2origin )
 import Gargantext.API.Node.Corpus.Update (addLanguageToCorpus)
 import Gargantext.API.Node.Types
-import Gargantext.Core (Lang(..), withDefaultLanguage, defaultLanguage)
+import Gargantext.Core (withDefaultLanguage, defaultLanguage)
 import Gargantext.Core.NodeStory (HasNodeStoryImmediateSaver, HasNodeArchiveStoryImmediateSaver, currentVersion, NgramsStatePatch')
 import Gargantext.API.Admin.Orchestrator.Types qualified as API
 import Gargantext.Core.Text.Corpus.Query qualified as API
 import Gargantext.Core.Text.Corpus.Parsers qualified as Parser (FileType(..), parseFormatC, _ParseFormatError)
-import Gargantext.Core.Text.List.Social (FlowSocialListWith(..))
 import Gargantext.Core.Types.Individu (User(..))
-import Gargantext.Core.Utils.Prefix (unPrefix, unPrefixSwagger)
+import Gargantext.Core.Utils.Prefix (unPrefix)
 import Gargantext.Database.Action.Flow (flowCorpus, getDataText, flowDataText, TermType(..){-, allDataOrigins-})
 import Gargantext.Database.Action.Flow.Types (FlowCmdM)
 import Gargantext.Database.Action.Mail (sendMail)
@@ -64,7 +62,6 @@ import Gargantext.Prelude.Config (gc_max_docs_parsers)
 import Gargantext.System.Logging ( logLocM, LogLevel(..) )
 import Gargantext.Utils.Jobs.Monad (JobHandle, MonadJobStatus(..))
 import Servant ( JSON, type (:>), FormUrlEncoded, Capture, Summary )
-import Servant.Job.Utils (jsonOptions)
 import Test.QuickCheck.Arbitrary (Arbitrary(..))
 
 ------------------------------------------------------------------------
@@ -136,41 +133,6 @@ info :: ApiInfo
 info = ApiInfo API.externalAPIs
 
 ------------------------------------------------------------------------
-------------------------------------------------------------------------
-data WithQuery = WithQuery
-  { _wq_query        :: !API.RawQuery
-  , _wq_databases    :: !Database
-  , _wq_datafield    :: !(Maybe Datafield)
-  , _wq_lang         :: !Lang
-  , _wq_node_id      :: !Int
-  , _wq_flowListWith :: !FlowSocialListWith
-  , _wq_pubmedAPIKey :: !(Maybe Text)
-  , _wq_epoAPIUser   :: !(Maybe Text)
-  , _wq_epoAPIToken  :: !(Maybe Text)
-  }
-  deriving (Show, Eq, Generic)
-
-makeLenses ''WithQuery
-instance FromJSON WithQuery where
-  parseJSON = genericParseJSON $ jsonOptions "_wq_"
-instance ToJSON WithQuery where
-  toJSON = genericToJSON $ jsonOptions "_wq_"
-instance ToSchema WithQuery where
-  declareNamedSchema = genericDeclareNamedSchema (unPrefixSwagger "_wq_")
-
-instance Arbitrary WithQuery where
-  arbitrary = WithQuery <$> arbitrary
-                        <*> arbitrary
-                        <*> arbitrary
-                        <*> arbitrary
-                        <*> arbitrary
-                        <*> arbitrary
-                        <*> arbitrary
-                        <*> arbitrary
-                        <*> arbitrary
-
-------------------------------------------------------------------------
-
 type AddWithQuery = Summary "Add with Query to corpus endpoint"
    :> "corpus"
      :> Capture "corpus_id" CorpusId

src/Gargantext/API/Node/Types.hs

@@ -19,12 +19,15 @@ import Data.ByteString.Base64 qualified as BSB64
 import Data.Swagger
 import Data.Text qualified as T
 import Gargantext.API.Node.Corpus.New.Types (FileType, FileFormat)
+import Gargantext.API.Node.Corpus.Types
 import Gargantext.Core (Lang(..))
+import Gargantext.Core.Text.Corpus.Query qualified as API
 import Gargantext.Core.Text.List.Social (FlowSocialListWith)
 import Gargantext.Core.Utils.Prefix (unPrefixSwagger)
 import Gargantext.Database.GargDB qualified as GargDB
 import Gargantext.Prelude
 import Servant.Job.Utils (jsonOptions)
+import Test.QuickCheck
 import Web.FormUrlEncoded          (FromForm, ToForm)
 
 -------------------------------------------------------
@@ -77,3 +80,36 @@ instance GargDB.SaveFile NewWithFile where
 
 --instance GargDB.ReadFile NewWithFile where
 --  readFile' = TIO.readFile
+
+data WithQuery = WithQuery
+  { _wq_query        :: !API.RawQuery
+  , _wq_databases    :: !Database
+  , _wq_datafield    :: !(Maybe Datafield)
+  , _wq_lang         :: !Lang
+  , _wq_node_id      :: !Int
+  , _wq_flowListWith :: !FlowSocialListWith
+  , _wq_pubmedAPIKey :: !(Maybe Text)
+  , _wq_epoAPIUser   :: !(Maybe Text)
+  , _wq_epoAPIToken  :: !(Maybe Text)
+  }
+  deriving (Show, Eq, Generic)
+
+makeLenses ''WithQuery
+instance FromJSON WithQuery where
+  parseJSON = genericParseJSON $ jsonOptions "_wq_"
+instance ToJSON WithQuery where
+  toJSON = genericToJSON $ jsonOptions "_wq_"
+instance ToSchema WithQuery where
+  declareNamedSchema = genericDeclareNamedSchema (unPrefixSwagger "_wq_")
+
+instance Arbitrary WithQuery where
+  arbitrary = WithQuery <$> arbitrary
+                        <*> arbitrary
+                        <*> arbitrary
+                        <*> arbitrary
+                        <*> arbitrary
+                        <*> arbitrary
+                        <*> arbitrary
+                        <*> arbitrary
+                        <*> arbitrary
+

src/Gargantext/API/Routes.hs

@@ -16,6 +16,7 @@ Portability : POSIX
 {-# LANGUAGE TypeOperators        #-}
 {-# LANGUAGE TypeApplications     #-}
 {-# LANGUAGE UndecidableInstances #-}
+{-# OPTIONS_GHC -fno-warn-orphans #-} -- instance HasSwagger (WithCustomErrorScheme GargAPI)
 
 module Gargantext.API.Routes
       where
@@ -29,7 +30,6 @@ import Gargantext.API.Admin.FrontEnd (FrontEndAPI)
 import Gargantext.API.Auth.PolicyCheck
 import Gargantext.API.Context
 import Gargantext.API.Count  (CountAPI, count, Query)
-import Gargantext.API.Errors (GargErrorScheme (..))
 import Gargantext.API.Errors.Types
 import Gargantext.API.GraphQL qualified as GraphQL
 import Gargantext.API.Members (MembersAPI, members)
@@ -39,13 +39,13 @@ import Gargantext.API.Node
 import Gargantext.API.Node.Contact qualified as Contact
 import Gargantext.API.Node.Corpus.Annuaire qualified as Annuaire
 import Gargantext.API.Node.Corpus.Export qualified as CorpusExport
-import Gargantext.API.Node.Corpus.Export.Types qualified as CorpusExport
 import Gargantext.API.Node.Corpus.New qualified as New
 import Gargantext.API.Node.Document.Export qualified as DocumentExport
 import Gargantext.API.Node.Document.Export.Types qualified as DocumentExport
 import Gargantext.API.Node.ShareURL qualified as ShareURL
 import Gargantext.API.Prelude
 import Gargantext.API.Public qualified as Public
+import Gargantext.API.Routes.Types
 import Gargantext.Core.Types.Individu (User(..))
 import Gargantext.Core.Viz.Graph.API
 import Gargantext.Database.Admin.Types.Hyperdata
@@ -54,41 +54,17 @@ import Gargantext.Database.Prelude (HasConfig(..))
 import Gargantext.Prelude
 import Gargantext.Prelude.Config (gc_max_docs_scrapers)
 import Gargantext.Utils.Jobs (serveJobsAPI, MonadJobStatus(..))
-import Network.Wai (requestHeaders)
 import Servant
 import Servant.Auth as SA
 import Servant.Auth.Swagger ()
-import Servant.Ekg
-import Servant.Server.Internal.Delayed
-import Servant.Server.Internal.DelayedIO
 import Servant.Swagger
 import Servant.Swagger.UI
-import qualified Data.List as L
-
-data WithCustomErrorScheme a
-
-instance (HasServer subApi ctx) => HasServer (WithCustomErrorScheme subApi) ctx where
-  type ServerT (WithCustomErrorScheme subApi) m = GargErrorScheme -> ServerT subApi m
-  hoistServerWithContext _ pc nt s = hoistServerWithContext (Proxy :: Proxy subApi) pc nt . s
-  route Proxy ctx d = route (Proxy :: Proxy subApi) ctx (d `addHeaderCheck` getErrorScheme)
-    where
-      getErrorScheme :: DelayedIO GargErrorScheme
-      getErrorScheme = withRequest $ \rq -> do
-        let hdrs = requestHeaders rq
-            in case L.lookup "X-Garg-Error-Scheme" hdrs of
-                 Nothing     -> pure GES_old
-                 Just "new"  -> pure GES_new
-                 Just _      -> pure GES_old
+
+type GargAPI = MkGargAPI (GargAPIVersion GargAPI')
 
 instance HasSwagger (WithCustomErrorScheme GargAPI) where
     toSwagger _ = toSwagger (Proxy :: Proxy GargAPI)
 
-instance HasEndpoint sub => HasEndpoint (WithCustomErrorScheme sub) where
-  getEndpoint _ = getEndpoint (Proxy :: Proxy sub)
-  enumerateEndpoints _ = enumerateEndpoints (Proxy :: Proxy sub)
-
-type GargAPI = MkGargAPI (GargAPIVersion GargAPI')
-
 type MkGargAPI sub = "api" :> Summary "API " :> sub
 --- | TODO          :<|> Summary "Latest API" :> GargAPI'
 

src/Gargantext/API/Routes/Named.hs

+
+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+
+module Gargantext.API.Routes.Named where
+
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.API.Admin.Auth (ForgotPasswordAsyncParams)
+import Gargantext.API.Admin.Auth.Types
+import Gargantext.API.Admin.Orchestrator.Types
+import Gargantext.API.Routes.Named.Public
+import Gargantext.API.Routes.Named.Private
+import Servant.API ((:>), (:-), JSON, ReqBody, Post, Get, QueryParam)
+import Servant.API.Description (Summary)
+import Servant.API.NamedRoutes
+
+type GargAPI = NamedRoutes (MkGargAPI (GargAPIVersion GargAPI'))
+
+
+data MkGargAPI sub mode = MkGargAPI
+  { mkGargAPI :: mode :- "api" :> Summary "API " :> NamedRoutes sub
+  } deriving Generic
+
+
+data GargAPIVersion sub mode = GargAPIVersion
+  { gargAPIVersion :: mode :- "v1.0" :> Summary "Garg API Version " :> NamedRoutes sub
+  } deriving Generic
+
+
+data GargAPI' mode = GargAPI'
+  { gargAuthAPI                :: mode :- NamedRoutes AuthAPI
+  , gargForgotPasswordAPI      :: mode :- "forgot-password" :> NamedRoutes ForgotPasswordAPI
+  , gargForgotPasswordAsyncAPI :: mode :- "async" :> "forgot-password" :> NamedRoutes ForgotPasswordAsyncAPI
+  , gargVersionAPI             :: mode :- NamedRoutes GargVersion
+  , gargPrivateAPI             :: mode :- NamedRoutes GargPrivateAPI
+  , gargPublicAPI              :: mode :- "public" :> NamedRoutes GargPublicAPI
+  } deriving Generic
+
+
+data AuthAPI mode = AuthAPI
+  { authEp :: mode :- "auth"  :> Summary "AUTH API"
+                              :> ReqBody '[JSON] AuthRequest
+                              :> Post    '[JSON] AuthResponse
+  } deriving Generic
+
+
+data ForgotPasswordAPI mode = ForgotPasswordAPI
+  { forgotPasswordPostEp :: mode :- Summary "Forgot password POST API"
+                                 :> ReqBody '[JSON] ForgotPasswordRequest
+                                 :> Post '[JSON] ForgotPasswordResponse
+  , forgotPasswordGetEp  :: mode :- Summary "Forgot password GET API"
+                                 :> QueryParam "uuid" Text
+                                 :> Get '[JSON] ForgotPasswordGet
+  } deriving Generic
+
+
+data ForgotPasswordAsyncAPI mode = ForgotPasswordAsyncAPI
+  { forgotPasswordAsyncEp :: mode :- Summary "Forgot password asnc"
+                                  :> AsyncJobs JobLog '[JSON] ForgotPasswordAsyncParams JobLog
+  } deriving Generic
+
+
+data GargVersion mode = GargVersion
+  { gargVersionEp :: "version" :> Summary "Backend version" :> Get '[JSON] Text
+  } deriving Generic

src/Gargantext/API/Routes/Named/Contact.hs

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+module Gargantext.API.Routes.Named.Contact (
+  -- * Routes types
+    ContactAPI(..)
+  , ContactAsyncAPI(..)
+
+  -- * API types (appears in the routes)
+  , AddContactParams(..)
+  ) where
+
+
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.API.Admin.Orchestrator.Types
+import Gargantext.API.Routes.Named.Node (NodeNodeAPI(..))
+import Gargantext.Database.Admin.Types.Hyperdata.Contact
+import Gargantext.Database.Admin.Types.Node
+import Servant
+
+
+data ContactAPI mode = ContactAPI
+  { contactAsyncAPI :: mode :- "contact" :> Summary "Contact endpoint" :> NamedRoutes ContactAsyncAPI
+  , getContactEp    :: mode :- Capture "contact_id" NodeId :> NamedRoutes (NodeNodeAPI HyperdataContact)
+  } deriving Generic
+
+
+newtype ContactAsyncAPI mode = ContactAsyncAPI
+  { addContactAsyncEp :: mode :- AsyncJobs JobLog '[JSON] AddContactParams JobLog
+  } deriving Generic
+
+
+data AddContactParams = AddContactParams         { firstname :: !Text, lastname :: !Text }
+                      | AddContactParamsAdvanced { firstname :: !Text
+                                                 , lastname  :: !Text
+                                                 -- TODO add others fields
+                                                 }
+    deriving Generic

src/Gargantext/API/Routes/Named/Context.hs

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+
+module Gargantext.API.Routes.Named.Context where
+
+import GHC.Generics
+import Gargantext.Database.Admin.Types.Node
+import Servant
+
+data ContextAPI mode a = ContextAPI
+  { getNodeEp :: mode :- Get '[JSON] (Node a)
+  } deriving Generic

src/Gargantext/API/Routes/Named/Corpus.hs

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+module Gargantext.API.Routes.Named.Corpus (
+  -- * Routes types
+    CorpusExportAPI(..)
+  , AddWithForm(..)
+  , AddWithQuery(..)
+  ) where
+
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.API.Admin.Orchestrator.Types
+import Gargantext.API.Node.Corpus.Annuaire hiding (AddWithForm)
+import Gargantext.API.Node.Corpus.Export.Types
+import Gargantext.API.Node.Types
+import Gargantext.Core.Text.Ngrams (NgramsType(..))
+import Gargantext.Database.Admin.Types.Node
+import Servant
+
+--------------------------------------------------
+newtype CorpusExportAPI mode = CorpusExportAPI
+  { corpusExportEp :: mode :- Summary "Corpus Export"
+                           :> "export"
+                           :> QueryParam "listId"     ListId
+                           :> QueryParam "ngramsType" NgramsType
+                           :> Get '[JSON] (Headers '[Servant.Header "Content-Disposition" Text] Corpus)
+  } deriving Generic
+
+newtype AddWithForm mode = AddWithForm
+  { addWithFormEp :: mode :- Summary "Add with FormUrlEncoded to annuaire endpoint"
+                          :> "annuaire"
+                          :> Capture "annuaire_id" AnnuaireId
+                          :> "add"
+                          :> "form"
+                          :> "async"
+                          :> AsyncJobs JobLog '[FormUrlEncoded] AnnuaireWithForm JobLog
+  } deriving Generic
+
+
+newtype AddWithQuery mode = AddWithQuery
+  { addWithQueryEp :: mode :- Summary "Add with Query to corpus endpoint"
+                           :> "corpus"
+                           :> Capture "corpus_id" CorpusId
+                           :> "query"
+                           :> AsyncJobs JobLog '[JSON] WithQuery JobLog
+  } deriving Generic

src/Gargantext/API/Routes/Named/Count.hs

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+module Gargantext.API.Routes.Named.Count (
+  -- * Routes types
+    CountAPI(..)
+
+  -- * Re-exports
+  , module X
+  ) where
+
+import GHC.Generics
+import Servant
+import Gargantext.API.Count as X hiding (CountAPI)
+
+
+newtype CountAPI mode = CountAPI
+  { postCountsEp :: mode :- Post '[JSON] X.Counts
+  } deriving Generic

src/Gargantext/API/Routes/Named/Document.hs

+{-# LANGUAGE DeriveGeneric   #-}
+{-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE TypeOperators   #-}
+module Gargantext.API.Routes.Named.Document (
+  -- * Routes types
+    DocumentsFromWriteNodesAPI(..)
+  , DocumentUploadAPI(..)
+  , DocumentExportAPI(..)
+
+  -- * API types
+  , Params(..)
+  , DocumentUpload(..)
+
+  -- * functions and lenses
+  , du_title
+  , du_sources
+  , du_language
+  , du_date
+  , du_authors
+  , du_abstract
+  ) where
+
+import Control.Lens
+import Data.Aeson
+import Data.Swagger hiding (fieldLabelModifier)
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.API.Admin.Orchestrator.Types
+import Gargantext.API.Node.Document.Export.Types
+import Gargantext.Core
+import Gargantext.Core.Text.List.Social
+import Gargantext.Core.Utils.Prefix
+import Gargantext.Utils.Servant (ZIP)
+import Prelude
+import Servant
+
+newtype DocumentExportAPI mode = DocumentExportAPI
+  { documentExportAPI ::
+      mode :- Summary "Document Export"
+           :> "export"
+           :> ( "json"
+                :> Get '[JSON] (Headers '[Servant.Header "Content-Disposition" Text] DocumentExport)
+              :<|> "json.zip"
+                :> Get '[ZIP] (Headers '[Servant.Header "Content-Disposition" Text] DocumentExportZIP)
+              :<|> "csv"
+                :> Get '[PlainText] (Headers '[Servant.Header "Content-Disposition" Text] Text) )
+  } deriving Generic
+
+newtype DocumentsFromWriteNodesAPI mode = DocumentsFromWriteNodesAPI
+  { docFromWriteNodesEp :: mode :- Summary " Documents from Write nodes."
+                                :> AsyncJobs JobLog '[JSON] Params JobLog
+  } deriving Generic
+
+
+newtype DocumentUploadAPI mode = DocumentUploadAPI
+  { uploadDocAsyncEp :: mode :- Summary " Document upload"
+                             :> "document"
+                             :> "upload"
+                             :> "async"
+                             :> AsyncJobs JobLog '[JSON] DocumentUpload JobLog
+  } deriving Generic
+
+
+data Params = Params
+  { id         :: Int
+  , paragraphs :: Text
+  , lang       :: Lang
+  , selection  :: FlowSocialListWith
+  }
+  deriving (Generic, Show)
+
+
+data DocumentUpload = DocumentUpload
+  { _du_abstract :: Text
+  , _du_authors  :: Text
+  , _du_sources  :: Text
+  , _du_title    :: Text
+  , _du_date     :: Text
+  , _du_language :: Text
+  }
+  deriving Generic
+
+
+--
+-- instances
+--
+
+instance FromJSON Params where
+  parseJSON = genericParseJSON defaultOptions
+
+instance ToJSON Params where
+  toJSON = genericToJSON defaultOptions
+
+instance ToSchema Params
+
+$(makeLenses ''DocumentUpload)
+
+instance ToSchema DocumentUpload
+
+instance FromJSON DocumentUpload
+  where
+    parseJSON = genericParseJSON
+            ( defaultOptions { sumEncoding = ObjectWithSingleField
+                            , fieldLabelModifier = unCapitalize . dropPrefix "_du_"
+                            , omitNothingFields = True
+                            }
+            )
+
+instance ToJSON DocumentUpload
+  where
+    toJSON = genericToJSON
+           ( defaultOptions { sumEncoding = ObjectWithSingleField
+                            , fieldLabelModifier = unCapitalize . dropPrefix "_du_"
+                            , omitNothingFields = True
+                            }
+           )
+

src/Gargantext/API/Routes/Named/File.hs

+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE TypeOperators #-}
+module Gargantext.API.Routes.Named.File (
+  -- * Routes types
+    FileAPI(..)
+  , FileAsyncAPI(..)
+  ) where
+
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.API.Admin.Orchestrator.Types
+import Gargantext.API.Node.File
+import Gargantext.API.Node.Types
+import Servant
+
+data FileAPI mode = FileAPI
+  { fileDownloadEp :: mode :- Summary "File download"
+                           :> "download"
+                           :> Get '[RESPONSE] (Headers '[Servant.Header "Content-Type" Text] BSResponse)
+  } deriving Generic
+
+
+data FileAsyncAPI mode = FileAsyncAPI
+  { addFileAsyncEp :: mode :- Summary "File Async Api"
+                           :> "file"
+                           :> "add"
+                           :> AsyncJobs JobLog '[FormUrlEncoded] NewWithFile JobLog
+  } deriving Generic
+

src/Gargantext/API/Routes/Named/FrameCalc.hs

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+
+module Gargantext.API.Routes.Named.FrameCalc where
+
+import Servant
+import GHC.Generics
+import Gargantext.API.Node.FrameCalcUpload (FrameCalcUpload)
+import Gargantext.API.Admin.Orchestrator.Types
+
+data FrameCalcAPI mode = FrameCalcAPI
+  { frameCalcUploadEp :: mode :- Summary " FrameCalc upload"
+                              :> "add"
+                              :> "framecalc"
+                              :> "async"
+                              :> AsyncJobs JobLog '[JSON] FrameCalcUpload JobLog
+  } deriving Generic
+

src/Gargantext/API/Routes/Named/List.hs

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+module Gargantext.API.Routes.Named.List where
+
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.API.Admin.Orchestrator.Types
+import Gargantext.API.Ngrams.List.Types
+import Gargantext.API.Ngrams.Types
+import Gargantext.API.Types (HTML)
+import Gargantext.Database.Admin.Types.Node
+import Gargantext.Utils.Servant qualified as GUS
+import Servant
+
+newtype GETAPI mode = GETAPI
+  { getListEp :: mode :- Summary "Get List"
+                      :> "lists"
+                      :> Capture "listId" ListId
+                      :> ( "json"
+                           :> Get '[JSON, HTML] (Headers '[Header "Content-Disposition" Text] NgramsList)
+                         :<|>  "json.zip"
+                           :> Get '[GUS.ZIP] (Headers '[Header "Content-Disposition" Text] NgramsListZIP)
+                         :<|> "csv"
+                           :> Get '[GUS.CSV] (Headers '[Header "Content-Disposition" Text] NgramsTableMap) )
+  } deriving Generic
+
+
+newtype JSONAPI mode = JSONAPI
+  { updateListJSONEp :: mode :- Summary "Update List"
+                             :> "lists"
+                             :> Capture "listId" ListId
+                             :> "add"
+                             :> "form"
+                             :> "async"
+                             :> AsyncJobs JobLog '[FormUrlEncoded] WithJsonFile JobLog
+  } deriving Generic
+
+
+newtype CSVAPI mode = CSVAPI
+  { updateListCSVEp :: mode :- Summary "Update List (legacy v3 CSV)"
+                            :> "lists"
+                            :> Capture "listId" ListId
+                            :> "csv"