Draft: Servant Api Specification

This PR does 3 things:

1. Specifies a modular definition for the Skete Servant api, along with associated clients and server. The design is granular to facilitate better testing (standalone clients are easier to test when their component apis are separate from the rest of the API)

2. Restructures the project to define a toplevel RestAPI.hs module, with client/server/util definitions in an associated RestAPI/* namespace.

3. Adds the Servant-* dependencies, cleans up old code.

Addresses #21

src/Distribution/Skete/Haskell/API/Features/Users.hs

@@ -2,10 +2,11 @@
 {-# LANGUAGE DataKinds #-}
 {-# LANGUAGE DeriveGeneric #-}
 {-# LANGUAGE TypeOperators #-}
-module Distribution.Skete.Haskell.RestAPI.Users
+module Distribution.Skete.Haskell.API.Features.Users
 ( -- * User API
   UsersApi(..)
 , usersApi
+, usersApiHandlers
   -- ** User endpoints
 , GetUsersApi
 , getUsersApi
@@ -49,15 +50,13 @@ module Distribution.Skete.Haskell.RestAPI.Users
 import Data.Proxy
 import Data.Text
 
+import Distribution.Skete.Haskell.API.Types.Users
 import GHC.Generics
 
 import Servant
 import Servant.API.Generic
 import Servant.HTML.Blaze
-
-
-data User
-data UserId
+import Servant.Server.Generic
 
 -- -------------------------------------------------------------------------- --
 -- Users API definition
@@ -74,21 +73,21 @@ data UserId
 --
 data UsersApi route
   = UsersApi
-  { getUsers :: route :- GetUsersApi
-  , postUsers :: route :- PostUsersApi
-  , getUserId :: route :- GetUserIdApi
-  , putUserId :: route :- PutUserIdApi
-  , deleteUserId :: route :- DeleteUserIdApi
-  , getUserPassword :: route :- GetUserPasswordApi
-  , putUserPassword :: route :- PutUserPasswordApi
-  , getUserEnabled :: route :- GetUserEnabledApi
-  , putUserEnabled :: route :- PutUserEnabledApi
-  , getUserManagement :: route :- GetUserManagementApi
+  { getUsers                 :: route :- GetUsersApi
+  , postUsers                :: route :- PostUsersApi
+  , getUserId                :: route :- GetUserIdApi
+  , putUserId                :: route :- PutUserIdApi
+  , deleteUserId             :: route :- DeleteUserIdApi
+  , getUserPassword          :: route :- GetUserPasswordApi
+  , putUserPassword          :: route :- PutUserPasswordApi
+  , getUserEnabled           :: route :- GetUserEnabledApi
+  , putUserEnabled           :: route :- PutUserEnabledApi
+  , getUserManagement        :: route :- GetUserManagementApi
   , getUserAccountManagement :: route :- GetUserAccountManagementApi
-  , getUserAdmins :: route :- GetUserAdminsApi
-  , postUserAdmins :: route :- PostUserAdminsApi
-  , putUserAdmins :: route :- PutUserAdminsApi
-  , deleteUserAdmins :: route :- DeleteUserAdminsApi
+  , getUserAdmins            :: route :- GetUserAdminsApi
+  , postUserAdmins           :: route :- PostUserAdminsApi
+  , putUserAdmins            :: route :- PutUserAdminsApi
+  , deleteUserAdmins         :: route :- DeleteUserAdminsApi
   } deriving Generic
 
 -- | Singleton instance for 'UsersApi'.
@@ -96,6 +95,29 @@ data UsersApi route
 usersApi :: Proxy (ToServantApi UsersApi)
 usersApi = genericApi (Proxy :: Proxy UsersApi)
 
+-- | Users Api Handlers.
+--
+-- TODO: Stubbed in Distribution.Skete.Haskell.API.Features.Users.Server
+--
+usersApiHandlers :: UsersApi AsServer
+usersApiHandlers = UsersApi
+  { getUsers = error "TODO: handler not yet written"
+  , postUsers = error "TODO: handler not yet written"
+  , getUserId = error "TODO: handler not yet written"
+  , putUserId = error "TODO: handler not yet written"
+  , deleteUserId = error "TODO: handler not yet written"
+  , getUserPassword = error "TODO: handler not yet written"
+  , putUserPassword = error "TODO: handler not yet written"
+  , getUserEnabled = error "TODO: handler not yet written"
+  , putUserEnabled = error "TODO: handler not yet written"
+  , getUserManagement = error "TODO: handler not yet written"
+  , getUserAccountManagement = error "TODO: handler not yet written"
+  , getUserAdmins = error "TODO: handler not yet written"
+  , postUserAdmins = error "TODO: handler not yet written"
+  , putUserAdmins = error "TODO: handler not yet written"
+  , deleteUserAdmins = error "TODO: handler not yet written"
+  }
+
 -- -------------------------------------------------------------------- --
 -- GET /users
 
@@ -107,7 +129,7 @@ type GetUsersApi
   :> Description "Get a list of all currently registered Hackage users \
                  \as either JSON or HTML."
   :> "users"
-  :> Get '[JSON, HTML] [User]
+  :> Get '[JSON, HTML] [UserName]
 
 -- | Singleton instance for 'GetUsersApi'.
 --
@@ -124,8 +146,8 @@ type PostUsersApi
   = Summary "Create a new user."
   :> Description "Create a new Hackage user via html POST request."
   :> "users"
-  :> ReqBody '[HTML] User
-  :> Post '[HTML] User
+  :> ReqBody '[HTML] UserInfo
+  :> Post '[HTML] UserInfo
 
 -- | Singleton instance for 'PostUsersApi'.
 --
@@ -142,8 +164,8 @@ type GetUserIdApi
   = Summary "Get user id info."
   :> Description "Get user id info for a particular Hackage user."
   :> "users"
-  :> Capture "username" User
-  :> Get '[JSON, HTML] User
+  :> Capture "username" UserId
+  :> Get '[JSON, HTML] UserInfo
 
 -- | Singleton instance for 'GetUeserIdApi'.
 --
@@ -162,7 +184,7 @@ type PutUserIdApi
   :> Description "Create a Hackage user."
   :> "users"
   :> Capture "username" UserId
-  :> Put '[JSON] User
+  :> Put '[JSON] UserInfo
 
 
 -- | Singleton instance for 'PostUserIdApi'.
@@ -173,7 +195,7 @@ putUserIdApi = Proxy
 -- -------------------------------------------------------------------- --
 -- DELETE /users/:username
 
--- ^ Equivalent to "DELETE /users/:username": accepts a DELETE request
+-- | Equivalent to "DELETE /users/:username": accepts a DELETE request
 -- to delete a particular hackage user.
 --
 type DeleteUserIdApi
@@ -193,7 +215,7 @@ deleteUserIdApi = Proxy
 -- -------------------------------------------------------------------- --
 -- GET /users/:username/password
 
--- ^ Equivalent to "GET /users/:username/password": accepts a GET request
+-- | Equivalent to "GET /users/:username/password": accepts a GET request
 -- to show the password change form as HTML. Note: TODO.
 --
 type GetUserPasswordApi
@@ -232,7 +254,7 @@ putUserPasswordApi = Proxy
 -- -------------------------------------------------------------------- --
 -- GET /users/:username/enabled
 
--- ^ Equivalent to "GET /users/:username/enabled": accepts a GET request
+-- | Equivalent to "GET /users/:username/enabled": accepts a GET request
 -- to check if a particular Hackage user is enabled as JSON.
 --
 type GetUserEnabledApi
@@ -251,7 +273,7 @@ getUserEnabledApi = Proxy
 -- -------------------------------------------------------------------- --
 -- PUT /users/:username/enabled
 
--- ^ Equivalant to "POST /users/:username/enabled": accepts a POST request
+-- | Equivalant to "POST /users/:username/enabled": accepts a POST request
 -- to enable a particular Hackage user as JSON.
 --
 type PutUserEnabledApi
@@ -260,8 +282,8 @@ type PutUserEnabledApi
   :> "users"
   :> Capture "username" UserId
   :> "enabled"
-  :> ReqBody '[JSON] Bool
-  :> Post '[JSON] Bool
+  :> ReqBody '[JSON] UserStatus
+  :> Post '[JSON] UserStatus
 
 -- | Singleton instance for 'PutUserEnabledApi'.
 --
@@ -271,7 +293,7 @@ putUserEnabledApi = Proxy
 -- -------------------------------------------------------------------- --
 -- GET /users/:username/manage
 
--- ^ Equivalant to "GET /users/:username/manage": accepts a GET request
+-- | Equivalant to "GET /users/:username/manage": accepts a GET request
 -- to return the user management page for Hackage user as HTML. Note: TODO
 --
 type GetUserManagementApi
@@ -290,7 +312,7 @@ getUserManagementApi = Proxy
 -- -------------------------------------------------------------------- --
 -- GET /users/:username/account-management
 
--- ^ Equivalent to "GET /users/:username/account-management": accepts a GET
+-- | Equivalent to "GET /users/:username/account-management": accepts a GET
 -- request for a Hackage user's personal account management page as HTML.
 -- Note: TODO
 --
@@ -310,7 +332,7 @@ getUserAccountManagementApi = Proxy
 -- -------------------------------------------------------------------- --
 -- GET /users/admins
 
--- ^ Equivalent to "GET /users/admins": Accepts a GET request for
+-- | Equivalent to "GET /users/admins": Accepts a GET request for
 -- the list of Hackage administrators as JSON or HTML.
 --
 type GetUserAdminsApi
@@ -318,7 +340,7 @@ type GetUserAdminsApi
   :> Description "Show the list of Hackage server administrators."
   :> "users"
   :> "admins"
-  :> Get '[JSON, HTML] [User]
+  :> Get '[JSON, HTML] [UserName]
 
 -- | Singleton instance for 'GetUserAdminsApi'.
 --
@@ -328,7 +350,7 @@ getUserAdminsApi = Proxy
 -- -------------------------------------------------------------------- --
 -- POST /users/admins
 
--- ^ Equivalent to "POST /users/admins": Accepts a POST request to
+-- | Equivalent to "POST /users/admins": Accepts a POST request to
 -- add a user to the list of Hackage admins as HTML. Note: TODO
 --
 type PostUserAdminsApi
@@ -336,8 +358,8 @@ type PostUserAdminsApi
   :> Description "Add a user to the list of Hackage administrators."
   :> "users"
   :> "admins"
-  :> ReqBody '[HTML] User
-  :> Post '[HTML] User
+  :> ReqBody '[HTML] UserInfo
+  :> Post '[HTML] UserInfo
 
 
 -- | Singleton instance for 'PostUserAdminsApi'.
@@ -348,7 +370,7 @@ postUserAdminsApi = Proxy
 -- -------------------------------------------------------------------- --
 -- PUT /users/admins
 
--- ^ Equivalent to "PUT /users/admins/user/:username": Accepts a PUT
+-- | Equivalent to "PUT /users/admins/user/:username": Accepts a PUT
 -- request to add a user to the list of Hackage admins as HTML.
 -- Note: TODO
 --
@@ -370,7 +392,7 @@ putUserAdminsApi = Proxy
 -- -------------------------------------------------------------------- --
 -- DELETE /users/admins
 
--- ^ Equivalent to "DELETE /users/admins/user/:username": Accepts a DELETE
+-- | Equivalent to "DELETE /users/admins/user/:username": Accepts a DELETE
 -- request to remove a user to the list of Hackage admins.
 -- Note: TODO
 --