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"
+                            :> "add"
+                            :> "form"
+                            :> "async"
+                            :> AsyncJobs JobLog '[FormUrlEncoded] WithTextFile JobLog
+  } deriving Generic

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

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+module Gargantext.API.Routes.Named.Metrics (
+  -- * Routes types
+
+    TreeAPI(..)
+  , ScatterAPI(..)
+  , ChartAPI(..)
+  , PieAPI(..)
+  ) where
+
+import Data.Text (Text)
+import Data.Time
+import Data.Vector
+import GHC.Generics
+import Gargantext.API.HashedResponse
+import Gargantext.API.Ngrams.NgramsTree
+import Gargantext.API.Ngrams.Types
+import Gargantext.Core.Types.Main
+import Gargantext.Core.Types.Query (Limit)
+import Gargantext.Core.Viz.Types
+import Gargantext.Database.Admin.Types.Metrics
+import Gargantext.Database.Admin.Types.Node
+import Servant
+
+
+data TreeAPI mode = TreeAPI
+  { treeChartEp       :: mode :- Summary " Tree API"
+                              :> QueryParam "from" UTCTime
+                              :> QueryParam "to"   UTCTime
+                              :> QueryParam  "list"       ListId
+                              :> QueryParamR "ngramsType" TabType
+                              :> QueryParamR "listType"   ListType
+                              :> Get '[JSON] (HashedResponse (ChartMetrics (Vector NgramsTree)))
+  , treeChartUpdateEp :: mode :- Summary "Tree Chart update"
+                              :> QueryParam  "list"       ListId
+                              :> QueryParamR "ngramsType" TabType
+                              :> QueryParamR "listType"   ListType
+                              :> Post '[JSON] ()
+  , treeHashEp        :: mode :- "hash"
+                              :> Summary "Tree Hash"
+                              :> QueryParam  "list"       ListId
+                              :> QueryParamR "ngramsType" TabType
+                              :> QueryParamR "listType"   ListType
+                              :> Get '[JSON] Text
+  } deriving Generic
+
+
+data ScatterAPI mode = ScatterAPI
+  { sepGenEp :: mode :- Summary "SepGen IncExc metrics"
+                     :> QueryParam  "list"       ListId
+                     :> QueryParamR "ngramsType" TabType
+                     :> QueryParam  "limit"      Limit
+                     :> Get '[JSON] (HashedResponse Metrics)
+  , scatterUpdateEp :: mode :- Summary "Scatter update"
+                            :> QueryParam  "list"       ListId
+                            :> QueryParamR "ngramsType" TabType
+                            :> QueryParam  "limit"      Limit
+                            :> Post '[JSON] ()
+  , scatterHashEp :: mode :- "hash"
+                          :> Summary "Scatter Hash"
+                          :> QueryParam  "list"       ListId
+                          :> QueryParamR "ngramsType" TabType
+                          :> Get '[JSON] Text
+  } deriving Generic
+
+
+data PieAPI mode = PieAPI
+  { getPieChartEp :: mode :- Summary "Pie Chart"
+                          :> QueryParam "from" UTCTime
+                          :> QueryParam "to"   UTCTime
+                          :> QueryParam  "list"       ListId
+                          :> QueryParamR "ngramsType" TabType
+                          :> Get '[JSON] (HashedResponse (ChartMetrics Histo))
+  , pieChartUpdateEp :: mode :- Summary "Pie Chart update"
+                             :> QueryParam  "list"       ListId
+                             :> QueryParamR "ngramsType" TabType
+                             :> QueryParam  "limit"      Limit
+                             :> Post '[JSON] ()
+  , pieHashEp :: mode :- "hash"
+                      :> Summary "Pie Hash"
+                      :> QueryParam  "list"       ListId
+                      :> QueryParamR "ngramsType" TabType
+                      :> Get '[JSON] Text
+  } deriving Generic
+
+
+data ChartAPI mode = ChartAPI
+  { getChartEp :: mode :- Summary " Chart API"
+                       :> QueryParam "from" UTCTime
+                       :> QueryParam "to"   UTCTime
+                       :> QueryParam  "list"       ListId
+                       :> QueryParamR "ngramsType" TabType
+                       :> Get '[JSON] (HashedResponse (ChartMetrics Histo))
+  , updateChartEp :: mode :- Summary "Chart update"
+                          :> QueryParam  "list"       ListId
+                          :> QueryParamR "ngramsType" TabType
+                          :> QueryParam  "limit"      Limit
+                          :> Post '[JSON] ()
+  , chartHashEp :: mode :- "hash"
+                        :> Summary "Chart Hash"
+                        :> QueryParam  "list"       ListId
+                        :> QueryParamR "ngramsType" TabType
+                        :> Get '[JSON] Text
+  } deriving Generic
+

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

+
+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+
+module Gargantext.API.Routes.Named.Private (
+  -- * Routes types
+    GargPrivateAPI
+  , GargPrivateAPI'(..)
+  , GargAdminAPI(..)
+  , NodeEndpoint(..)
+  , MembersAPI(..)
+  ) where
+
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.API.Admin.Auth.Types
+import Gargantext.API.Auth.PolicyCheck
+import Gargantext.API.Routes.Named.Contact
+import Gargantext.API.Routes.Named.Context
+import Gargantext.API.Routes.Named.Corpus
+import Gargantext.API.Routes.Named.Count
+import Gargantext.API.Routes.Named.Document
+import Gargantext.API.Routes.Named.Metrics
+import Gargantext.API.Routes.Named.Node
+import Gargantext.API.Routes.Named.List qualified as List
+import Gargantext.API.Routes.Named.Share
+import Gargantext.API.Routes.Named.Tree
+import Gargantext.API.Routes.Named.Table
+import Gargantext.API.Routes.Named.Viz
+import Gargantext.Database.Admin.Types.Hyperdata.Any
+import Gargantext.Database.Admin.Types.Hyperdata.Corpus
+import Gargantext.Database.Admin.Types.Node
+import Servant.API
+import Servant.Auth qualified as SA
+
+
+type MkProtectedAPI private = SA.Auth '[SA.JWT, SA.Cookie] AuthenticatedUser :> private
+
+
+newtype GargPrivateAPI mode = GargPrivateAPI
+  { mkPrivateAPI :: mode :- MkProtectedAPI (NamedRoutes GargPrivateAPI')
+  } deriving Generic
+
+
+data GargPrivateAPI' mode = GargPrivateAPI'
+  { gargAdminAPI :: mode :- NamedRoutes GargAdminAPI
+  , nodeEp       :: mode :- NamedRoutes NodeEndpoint
+  , contextEp    :: mode :- "context"  :> Summary "Node endpoint"
+                                       :> Capture "node_id" ContextId
+                                       :> NamedRoutes (ContextAPI HyperdataAny)
+  , corpusNodeAPI :: mode :- "corpus"  :> Summary "Corpus endpoint"
+                                       :> Capture "corpus_id" CorpusId
+                                       :> NamedRoutes (NodeAPI HyperdataCorpus)
+  , corpusNodeNodeAPI :: mode :- "corpus" :> Summary "Corpus endpoint"
+                                          :> Capture "node1_id" NodeId
+                                          :> "document"
+                                          :> Capture "node2_id" NodeId
+                                          :> NamedRoutes (NodeNodeAPI HyperdataAny)
+  , corpusExportAPI :: mode :- "corpus" :> Capture "node_id" CorpusId
+                                        :> NamedRoutes CorpusExportAPI
+  , annuaireEp :: mode :- "annuaire" :> Summary "Annuaire endpoint"
+                                     :> Capture "annuaire_id" AnnuaireId
+                                     :> NamedRoutes (NodeAPI HyperdataAnnuaire)
+  , contactAPI :: mode :- "annuaire" :> Summary "Contact endpoint"
+                                     :> Capture "annuaire_id" NodeId
+                                     :> NamedRoutes ContactAPI
+  , tableNgramsAPI :: mode :- "document" :> Summary "Document endpoint"
+                                         :> Capture "doc_id" DocId
+                                         :> "ngrams"
+                                         :> NamedRoutes TableNgramsAPI
+  , documentExportAPI :: mode :- "texts" :> Capture "node_id" DocId
+                                         :> NamedRoutes DocumentExportAPI
+  , countAPI :: mode :- "count" :> Summary "Count endpoint"
+                                :> ReqBody '[JSON] Query
+                                :> NamedRoutes CountAPI
+  , graphAPI :: mode :- "graph" :> Summary "Graph endpoint"
+                                :> Capture "graph_id" NodeId
+                                :> NamedRoutes GraphAPI
+  , treeAPI :: mode :- "tree" :> Summary "Tree endpoint"
+                              :> Capture "tree_id" NodeId
+                              :> PolicyChecked (NamedRoutes TreeAPI)
+  , treeFlatAPI :: mode :- "treeflat" :> Summary "Flat tree endpoint"
+                                      :> Capture "tree_id" NodeId
+                                      :> NamedRoutes TreeFlatAPI
+  , membersAPI     :: mode :- "members" :> Summary "Team node members" :> NamedRoutes MembersAPI
+  , addWithFormEp  :: mode :- NamedRoutes AddWithForm
+  , addWithQueryEp :: mode :- NamedRoutes AddWithQuery
+  , listGetAPI     :: mode :- NamedRoutes List.GETAPI
+  , listJsonAPI    :: mode :- NamedRoutes List.JSONAPI
+  , listCsvAPI     :: mode :- NamedRoutes List.CSVAPI
+  , shareUrlEp     :: mode :- "shareurl" :> NamedRoutes ShareURL
+  } deriving Generic
+
+
+data GargAdminAPI mode = GargAdminAPI
+  { rootsEp       :: mode :- "user"  :> Summary "First user endpoint" :> NamedRoutes Roots
+  , adminNodesAPI :: mode :- "nodes" :> Summary "Nodes endpoint"
+                                     :> ReqBody '[JSON] [NodeId]
+                                     :> NamedRoutes NodesAPI
+  } deriving Generic
+
+
+data NodeEndpoint mode = NodeEndpoint
+  { nodeEndpointAPI :: mode :- "node" :> Summary "Node endpoint"
+                                      :> Capture "node_id" NodeId
+                                      :> NamedRoutes (NodeAPI HyperdataAny)
+  } deriving Generic
+
+
+data MembersAPI mode = MembersAPI
+  { getMembersEp :: mode :- Get '[JSON] [Text]
+  }
+

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

+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE TypeOperators #-}
+module Gargantext.API.Routes.Named.Public where
+
+import GHC.Generics
+import Gargantext.API.Public qualified as Public
+import Gargantext.API.Routes.Named.File
+import Gargantext.Database.Admin.Types.Node ( NodeId )
+import Servant.API
+
+data GargPublicAPI mode = GargPublicAPI
+  { publicHomeAPI :: mode :- NamedRoutes HomeAPI
+  , publicNodeAPI :: mode :- NamedRoutes NodeAPI
+  } deriving Generic
+
+data HomeAPI mode = HomeAPI
+  { homeEp :: mode :- Summary "Public Home API" :> Get '[JSON] [Public.PublicData]
+  } deriving Generic
+
+data NodeAPI mode = NodeAPI
+  { nodeEp :: mode :- Summary "Public Node API" :> Capture "node" NodeId :> "file" :> NamedRoutes FileAPI
+  } deriving Generic

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

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+module Gargantext.API.Routes.Named.Search (
+  -- * Routes types
+    SearchAPI(..)
+
+  -- * API types (appears in the routes)
+  , SearchType(..)
+  , SearchQuery(..)
+  , SearchResult(..)
+  , SearchResultTypes(..)
+  ) where
+
+
+import Data.Aeson
+import Data.Swagger
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.Core.Text.Corpus.Query (RawQuery (..))
+import Gargantext.Core.Types.Query (Limit, Offset)
+import Gargantext.Core.Types.Search
+import Gargantext.Core.Utils.Prefix (unPrefixSwagger)
+import Gargantext.Database.Query.Facet
+import Prelude
+import Servant
+import Test.QuickCheck
+
+
+-- TODO-ACCESS: CanSearch? or is it part of CanGetNode
+-- TODO-EVENTS: No event, this is a read-only query.
+data SearchAPI results mode = SearchAPI
+  { searchEp :: mode :- Summary "Search endpoint"
+                     :> ReqBody '[JSON] SearchQuery
+                     :> QueryParam "offset" Offset
+                     :> QueryParam "limit"  Limit
+                     :> QueryParam "order"  OrderBy
+                     :> Post '[JSON] results
+  } deriving Generic
+
+
+data SearchType = SearchDoc | SearchContact | SearchDocWithNgrams
+  deriving Generic
+
+
+data SearchQuery = SearchQuery
+  { query    :: !RawQuery
+  , expected :: !SearchType
+  } deriving Generic
+
+
+newtype SearchResult =
+  SearchResult { result :: SearchResultTypes }
+    deriving Generic
+
+
+data SearchResultTypes =
+    SearchResultDoc { docs     :: ![Row] }
+  | SearchResultContact  { contacts :: ![Row] }
+  | SearchNoResult      { message  :: !Text }
+  deriving Generic
+
+
+--
+-- instances
+--
+
+instance FromJSON SearchResult where
+  parseJSON = genericParseJSON defaultOptions
+
+instance ToJSON SearchResult where
+  toJSON = genericToJSON defaultOptions
+
+instance ToSchema SearchResult
+
+instance Arbitrary SearchResult where
+  arbitrary = SearchResult <$> arbitrary
+
+instance FromJSON SearchResultTypes where
+  parseJSON = genericParseJSON (defaultOptions { sumEncoding = defaultTaggedObject })
+
+instance ToJSON SearchResultTypes where
+  toJSON = genericToJSON (defaultOptions { sumEncoding = defaultTaggedObject })
+
+instance Arbitrary SearchResultTypes where
+  arbitrary = do
+    srd <- SearchResultDoc     <$> arbitrary
+    src <- SearchResultContact <$> arbitrary
+    srn <- pure $ SearchNoResult "No result because.."
+    elements [srd, src, srn]
+
+instance ToSchema SearchResultTypes where
+  declareNamedSchema = genericDeclareNamedSchema (unPrefixSwagger "")
+
+instance FromJSON SearchQuery where
+  parseJSON = genericParseJSON defaultOptions
+
+instance ToJSON SearchQuery where
+  toJSON = genericToJSON defaultOptions
+
+instance ToSchema SearchQuery
+
+instance Arbitrary SearchQuery where
+  arbitrary = elements [SearchQuery (RawQuery "electrodes") SearchDoc]
+
+instance FromJSON SearchType where
+  parseJSON = genericParseJSON (defaultOptions { sumEncoding = ObjectWithSingleField })
+
+instance ToJSON SearchType where
+  toJSON = genericToJSON (defaultOptions { sumEncoding = ObjectWithSingleField })
+
+instance ToSchema SearchType
+
+instance Arbitrary SearchType where
+  arbitrary = elements [SearchDoc, SearchContact]

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

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+
+module Gargantext.API.Routes.Named.Share (
+  -- * Routes types
+    ShareNode(..)
+  , Unpublish(..)
+  , ShareURL(..)
+
+  -- * API types (which appears in the routes)
+  , ShareNodeParams(..)
+  ) where
+
+import Data.Aeson
+import Data.Swagger
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.Database.Admin.Types.Node
+import Gargantext.Utils.Aeson qualified as GUA
+import Prelude
+import Servant
+import Test.QuickCheck
+
+newtype ShareURL mode = ShareURL
+  { shareUrlEp :: mode :- Summary "Fetch URL for sharing a node"
+                       :> QueryParam "type" NodeType
+                       :> QueryParam "id" NodeId
+                       :> Get '[JSON] Text
+  } deriving Generic
+
+
+newtype ShareNode mode = ShareNode
+  { shareNodeEp :: mode :- Summary " Share Node with username"
+                        :> ReqBody '[JSON] ShareNodeParams
+                        :> Post    '[JSON] Int
+  } deriving Generic
+
+
+newtype Unpublish mode = Unpublish
+  { unpublishEp :: mode :- Summary " Unpublish Node" :> Capture "node_id" NodeId :> Put '[JSON] Int
+  } deriving Generic
+
+--
+-- API Types
+--
+data ShareNodeParams = ShareTeamParams   { username :: Text  }
+                     | SharePublicParams { node_id  :: NodeId }
+  deriving (Generic)
+
+--
+-- Instances
+--
+
+-- TODO unPrefix "pn_" FromJSON, ToJSON, ToSchema, adapt frontend.
+instance FromJSON  ShareNodeParams where
+  parseJSON = genericParseJSON (defaultOptions { sumEncoding = GUA.defaultTaggedObject })
+instance ToJSON    ShareNodeParams where
+  toJSON = genericToJSON (defaultOptions { sumEncoding = GUA.defaultTaggedObject })
+instance ToSchema  ShareNodeParams
+instance Arbitrary ShareNodeParams where
+  arbitrary = elements [ ShareTeamParams "user1"
+                       , SharePublicParams (UnsafeMkNodeId 1)
+                       ]

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

+{-# LANGUAGE DeriveGeneric   #-}
+{-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE TypeOperators   #-}
+
+module Gargantext.API.Routes.Named.Table (
+  -- * Routes types
+    TableAPI(..)
+  , TableNgramsAPI(..)
+  , TableNgramsApiGet(..)
+  , TableNgramsApiPut(..)
+  , RecomputeScoresNgramsApiGet(..)
+  , TableNgramsApiGetVersion(..)
+  , TableNgramsAsyncAPI(..)
+
+  -- * API types (appears in the routes)
+
+  , TableQuery(..)
+  , FacetTableResult
+  ) where
+
+import Data.Aeson.TH
+import Data.Swagger
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.API.Admin.Orchestrator.Types
+import Gargantext.API.HashedResponse
+import Gargantext.API.Ngrams.Types (TabType(..), UpdateTableNgramsCharts, Version, QueryParamR, Versioned, VersionedWithCount, NgramsTable, NgramsTablePatch)
+import Gargantext.Core.Text.Corpus.Query (RawQuery)
+import Gargantext.Core.Types (TableResult(..))
+import Gargantext.Core.Types.Main (ListType)
+import Gargantext.Core.Types.Query
+import Gargantext.Core.Utils.Prefix (unPrefix, unPrefixSwagger)
+import Gargantext.Database.Admin.Types.Node (ListId)
+import Gargantext.Database.Query.Facet.Types
+import Prelude
+import Servant
+import Test.QuickCheck
+
+
+data TableAPI mode = TableAPI
+  { getTableEp   :: mode :- Summary "Table API"
+                         :> QueryParam "tabType" TabType
+                         :> QueryParam "limit" Limit
+                         :> QueryParam "offset" Offset
+                         :> QueryParam "orderBy" OrderBy
+                         :> QueryParam "query" RawQuery
+                         :> QueryParam "year" Text
+                         :> Get    '[JSON] (HashedResponse FacetTableResult)
+  , postTableEp :: mode :- Summary "Table API (POST)"
+                        :> ReqBody '[JSON] TableQuery
+                        :> Post    '[JSON] FacetTableResult
+  , hashTableEp :: mode :- "hash"
+                        :> Summary "Hash Table"
+                        :> QueryParam "tabType" TabType
+                        :> Get '[JSON] Text
+  } deriving Generic
+
+
+data TableNgramsAPI mode = TableNgramsAPI
+  { tableNgramsGetAPI       :: mode :- NamedRoutes TableNgramsApiGet
+  , tableNgramsPutAPI       :: mode :- NamedRoutes TableNgramsApiPut
+  , recomputeScoresEp       :: mode :- NamedRoutes RecomputeScoresNgramsApiGet
+  , tableNgramsGetVersionEp :: mode :- "version" :> NamedRoutes TableNgramsApiGetVersion
+  , tableNgramsAsyncAPI     :: mode :- NamedRoutes TableNgramsAsyncAPI
+  } deriving Generic
+
+
+data TableNgramsApiGet mode = TableNgramsApiGet
+  { getNgramsTableEp :: mode :- Summary " Table Ngrams API Get"
+                             :> QueryParamR "ngramsType"  TabType
+                             :> QueryParamR "list"        ListId
+                             :> QueryParamR "limit"       Limit
+                             :> QueryParam  "offset"      Offset
+                             :> QueryParam  "listType"    ListType
+                             :> QueryParam  "minTermSize" MinSize
+                             :> QueryParam  "maxTermSize" MaxSize
+                             :> QueryParam  "orderBy"     OrderBy
+                             :> QueryParam  "search"      Text
+                             :> Get    '[JSON] (VersionedWithCount NgramsTable)
+  } deriving Generic
+
+
+data TableNgramsApiPut mode = TableNgramsApiPut
+  { putNgramsTableEp :: mode :- Summary " Table Ngrams API Change"
+                             :> QueryParamR "ngramsType" TabType
+                             :> QueryParamR "list"       ListId
+                             :> ReqBody '[JSON] (Versioned NgramsTablePatch)
+                             :> Put     '[JSON] (Versioned NgramsTablePatch)
+  } deriving Generic
+
+
+data RecomputeScoresNgramsApiGet mode = RecomputeScoresNgramsApiGet
+  { recomputeNgramsEp :: mode :- Summary " Recompute scores for ngrams table"
+                              :> QueryParamR "ngramsType"  TabType
+                              :> QueryParamR "list"        ListId
+                              :> "recompute" :> Post '[JSON] Int
+  } deriving Generic
+
+
+data TableNgramsApiGetVersion mode = TableNgramsApiGetVersion
+  { getTableNgramsVersion :: mode :- Summary " Table Ngrams API Get Version"
+                                  :> QueryParamR "ngramsType"  TabType
+                                  :> QueryParamR "list"        ListId
+                                  :> Get    '[JSON] Version
+  } deriving Generic
+
+
+data TableNgramsAsyncAPI mode = TableNgramsAsyncAPI
+  { updateTableNgramsChartsEp :: mode :- Summary "Table Ngrams Async API"
+                                      :> "async"
+                                      :> "charts"
+                                      :> "update"
+                                      :> AsyncJobs JobLog '[JSON] UpdateTableNgramsCharts JobLog
+  } deriving Generic
+
+
+data TableQuery = TableQuery
+  { tq_offset       :: Offset
+  , tq_limit        :: Limit
+  , tq_orderBy      :: OrderBy
+  , tq_view         :: TabType
+  , tq_query        :: RawQuery
+  } deriving Generic
+
+type FacetTableResult = TableResult FacetDoc
+
+--
+-- instances
+--
+
+$(deriveJSON (unPrefix "tq_") ''TableQuery)
+
+instance ToSchema TableQuery where
+  declareNamedSchema = genericDeclareNamedSchema (unPrefixSwagger "tq_")
+
+instance Arbitrary TableQuery where
+  arbitrary = elements [TableQuery { tq_offset = 0
+                                   , tq_limit = 10
+                                   , tq_orderBy = DateAsc
+                                   , tq_view = Docs
+                                   , tq_query = "electrodes" }]

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

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+
+module Gargantext.API.Routes.Named.Tree (
+  -- * Routes types
+    NodeTreeAPI(..)
+  , TreeFlatAPI(..)
+  ) where
+
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.Core.Types.Main
+import Gargantext.Database.Admin.Types.Node
+import Servant
+
+data NodeTreeAPI mode = NodeTreeAPI
+  { nodeTreeEp   :: mode :- QueryParams "type" NodeType :> Get '[JSON] (Tree NodeTree)
+  , firstLevelEp :: mode :- "first-level" :> QueryParams "type" NodeType :> Get '[JSON] (Tree NodeTree)
+  } deriving Generic
+
+
+data TreeFlatAPI mode = TreeFlatAPI
+  { getNodesEp :: mode :- QueryParams "type" NodeType :> QueryParam "query" Text :> Get '[JSON] [NodeTree]
+  } deriving Generic

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

+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DeriveGeneric #-}
+
+module Gargantext.API.Routes.Named.Viz (
+  -- * Routes types
+    PhyloAPI(..)
+  , GetPhylo(..)
+  , PostPhylo(..)
+  , GraphAPI(..)
+  , GraphAsyncAPI(..)
+  , GraphVersionsAPI(..)
+
+  -- * API types (appears in the routes)
+  , PhyloData(..)
+  , GraphVersions(..)
+  ) where
+
+import Data.Aeson
+import Data.Swagger
+import Data.Text (Text)
+import GHC.Generics
+import Gargantext.API.Admin.Orchestrator.Types ( JobLog )
+import Gargantext.Core.Types
+import Gargantext.Core.Types.Phylo
+import Gargantext.Core.Viz.Graph.Types
+import Gargantext.Core.Viz.LegacyPhylo (Level)
+import Gargantext.Core.Viz.Phylo
+import Gargantext.Core.Viz.Phylo.Legacy.LegacyMain (MinSizeBranch)
+import Prelude
+import Servant
+import Servant.Job.Async (AsyncJobsAPI)
+import Servant.XML.Conduit (XML)
+import Test.QuickCheck
+
+
+data PhyloAPI mode = PhyloAPI
+  { getPhyloEp  :: mode :- Summary "Phylo API" :> NamedRoutes GetPhylo
+  , postPhyloEp :: mode :- NamedRoutes PostPhylo
+  } deriving Generic
+
+
+newtype GetPhylo mode = GetPhylo
+  { getPhyloDataEp :: mode :- QueryParam "listId"      ListId
+                           :> QueryParam "level"       Level
+                           :> QueryParam "minSizeBranch" MinSizeBranch
+                           :> Get '[JSON] PhyloData
+  } deriving Generic
+
+
+newtype PostPhylo mode = PostPhylo
+  { postPhyloByListIdEp :: mode :- QueryParam "listId" ListId :> (Post '[JSON] NodeId)
+  } deriving Generic
+
+
+data GraphAPI mode = GraphAPI
+  { getGraphEp       :: mode :- Get '[JSON] HyperdataGraphAPI
+  , getGraphAsyncEp  :: mode :- "async" :> NamedRoutes GraphAsyncAPI
+  , cloneGraphEp     :: mode :- "clone" :> ReqBody '[JSON] HyperdataGraphAPI :> Post '[JSON] NodeId
+  , gexfEp           :: mode :- "gexf" :> Get '[XML] (Headers '[Servant.Header "Content-Disposition" Text] Graph)
+  , graphVersionsAPI :: mode :- "versions" :> NamedRoutes GraphVersionsAPI
+  } deriving Generic
+
+
+newtype GraphAsyncAPI mode = GraphAsyncAPI
+  { recomputeGraphEp :: mode :- Summary "Recompute graph"
+                             :> "recompute"
+                             :> AsyncJobsAPI JobLog () JobLog
+  } deriving Generic
+
+
+data GraphVersionsAPI mode = GraphVersionsAPI
+  { getGraphVersionsEp :: mode :- Summary "Graph versions" :> Get '[JSON] GraphVersions
+  , recomputeGraphVersionEp :: mode :- Summary "Recompute graph version" :> Post '[JSON] Graph
+  } deriving Generic
+
+
+data PhyloData = PhyloData { pd_corpusId :: NodeId
+                           , pd_listId   :: NodeId
+                           , pd_data     :: GraphData
+                           , pd_config   :: PhyloConfig
+                           }
+  deriving (Generic, Show, Eq)
+
+
+data GraphVersions = GraphVersions
+  { gv_graph :: Maybe Int
+  , gv_repo  :: Int
+  } deriving (Show, Generic)
+
+
+--
+-- instances
+--
+
+instance ToJSON PhyloData where
+  toJSON PhyloData{..} =
+    object [
+      "pd_corpusId" .= toJSON pd_corpusId
+    , "pd_listId"   .= toJSON pd_listId
+    , "pd_data"     .= toJSON pd_data
+    , "pd_config"   .= toJSON pd_config
+    ]
+
+instance FromJSON PhyloData where
+  parseJSON = withObject "PhyloData" $ \o -> do
+    pd_corpusId <- o .: "pd_corpusId"
+    pd_listId   <- o .: "pd_listId"
+    pd_data     <- o .: "pd_data"
+    pd_config   <- o .: "pd_config"
+    pure $ PhyloData{..}
+
+instance Arbitrary PhyloData where
+  arbitrary = PhyloData <$> arbitrary <*> arbitrary <*> arbitrary <*> arbitrary
+
+instance ToSchema PhyloData
+
+instance FromJSON GraphVersions
+
+instance ToJSON GraphVersions
+
+instance ToSchema GraphVersions
+

src/Gargantext/API/Routes/Types.hs

+{-# LANGUAGE TypeFamilies         #-}
+{-# LANGUAGE ScopedTypeVariables  #-}
+module Gargantext.API.Routes.Types where
+
+import Data.List qualified as L
+import Data.Proxy
+import Gargantext.API.Errors
+import Prelude
+import Servant.Ekg
+import Servant.Server
+import Servant.Server.Internal.DelayedIO
+import Servant.Server.Internal.Delayed
+import Network.Wai
+
+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
+
+instance HasEndpoint sub => HasEndpoint (WithCustomErrorScheme sub) where
+  getEndpoint _ = getEndpoint (Proxy :: Proxy sub)
+  enumerateEndpoints _ = enumerateEndpoints (Proxy :: Proxy sub)

test/Test/Offline/JSON.hs

@@ -7,22 +7,22 @@
 module Test.Offline.JSON (tests) where
 
 import Data.Aeson
+import Data.ByteString qualified as B
+import Data.ByteString.Lazy.Char8 qualified as C8
 import Data.Either
 import Gargantext.API.Errors
 import Gargantext.API.Node.Corpus.New
 import Gargantext.API.Node.Corpus.Types
+import Gargantext.API.Node.Types
 import Gargantext.Core.Types.Phylo
 import Gargantext.Core.Viz.Phylo.API
+import Gargantext.Database.Admin.Types.Node
+import Paths_gargantext
 import Prelude
 import Test.Tasty
 import Test.Tasty.HUnit
 import Test.Tasty.QuickCheck
 import Text.RawString.QQ
-import qualified Data.ByteString as B
-import qualified Data.ByteString.Lazy.Char8 as C8
-
-import Paths_gargantext
-import Gargantext.Database.Admin.Types.Node
 
 jsonRoundtrip :: (Show a, FromJSON a, ToJSON a, Eq a) => a -> Property
 jsonRoundtrip a =