Safe Haskell | None |
---|---|
Language | Haskell2010 |
This module can be used to describe the operations that can be performed against an external API that uses JSON as its serialization format.
It exposes functions tailored to get and post data in the JSON format and to unserialize the responses into types that can be converted form JSON.
Use the Ref
and RPC
types to describe the external API operations.
- data Ref response = Ref {}
- newtype RPC response request = RPC {}
- get :: FromJSON a => Session -> Ref a -> IO a
- post :: (Postable req, FromJSON res) => Session -> RPC res req -> req -> IO res
- put :: (Putable req, FromJSON res) => Session -> RPC res req -> req -> IO res
- rpc :: (ToJSON req, FromJSON res) => Session -> RPC res req -> req -> IO res
- delete :: FromJSON a => Session -> Ref a -> IO a
- getWith :: FromJSON a => Options -> Session -> Ref a -> IO a
- postWith :: (Postable req, FromJSON res) => Options -> Session -> RPC res req -> req -> IO res
- putWith :: (Putable req, FromJSON res) => Options -> Session -> RPC res req -> req -> IO res
- rpcWith :: (ToJSON req, FromJSON res) => Options -> Session -> RPC res req -> req -> IO res
- deleteWith :: FromJSON a => Options -> Session -> Ref a -> IO a
- query :: [(Text, Text)] -> Text
Documentation
A Ref represents an API resource whose contents can be retrieved with GET
We use the phantom type parameter response
so that we can use
this information for understanding what type of data the API
resource will return
For example, an API endpoint returning a list of User is modelled as follows:
usersRef :: Ref [User] usersRef = Ref "http://localhost:8080/users"
newtype RPC response request Source #
A Req represents an API resource whose contents can be retrieved with POST
We use the phantom type parameter response
so that we can use
this information for understanding what type of data the API
resource will return
Similarly, the request parameter is used to know what type of data can be posted to the endpoint.
For example, an API endpoint that receives a User and returns a list of Friendship is modelled as follows:
newFriendRpc :: User -> RPC [Friendship] User newFriendRpc User { userID } = RPC "http://localhost:8080/users/" <> userID <> "/friendships"
Interacting with an external API
get :: FromJSON a => Session -> Ref a -> IO a Source #
Gets the results form an API endpoint that responds in the JSON format.
users <- get sess usersRef mapM_ (print . userID) users
Posts some data to an API endpoint in any Postable
format
and gets the response in JSON format.
Friendships friends <- post sess (newFriendRpc user) user2 mapM_ (print . userID) friends
Puts some data to an API endpoint in any Putable
format
and gets the response in JSON format.
Friendships friends <- put sess (newFriendRpc user) user2 mapM_ (print . userID) friends
Posts some data to an API endpoint in any JSON format and gets the response in JSON format.
Friendships friends <- post sess (newFriendRpc user) user2 mapM_ (print . userID) friends
delete :: FromJSON a => Session -> Ref a -> IO a Source #
Sends as DELETE request to an API endpoint that responds in the JSON format.
Status { success } <- delete sess usersDeleteRef
Network functions with Options
getWith :: FromJSON a => Options -> Session -> Ref a -> IO a Source #
Gets the results form an API endpoint that responds in the JSON format. This function excepts additional options, such as custom headers
let opts = Network.Wreq.defaults & Network.Wreq.auth ?~ Network.Wreq.basicAuth "user" "pass" users <- getWith opts sess usersRef mapM_ (print . userID) users
:: (Postable req, FromJSON res) | |
=> Options | |
-> Session | |
-> RPC res req | |
-> req | The request payload |
-> IO res |
Posts some data to an API endpoint in any Postable
format
and gets the response in JSON format.
This function excepts additional options, such as custom headers
let opts = Network.Wreq.defaults & Network.Wreq.auth ?~ Network.Wreq.basicAuth "user" "pass" Friendships friends <- post sess (newFriendRpc user) user2 mapM_ (print . userID) friends
:: (Putable req, FromJSON res) | |
=> Options | |
-> Session | |
-> RPC res req | |
-> req | The request payload |
-> IO res |
Puts some data to an API endpoint in any Putable
format
and gets the response in JSON format.
This function excepts additional options, such as custom headers
let opts = Network.Wreq.defaults & Network.Wreq.auth ?~ Network.Wreq.basicAuth "user" "pass" Friendships friends <- put sess (newFriendRpc user) user2 mapM_ (print . userID) friends
:: (ToJSON req, FromJSON res) | |
=> Options | |
-> Session | |
-> RPC res req | |
-> req | The request payload |
-> IO res |
Posts some data to an API endpoint in any JSON format and gets the response in JSON format. This function excepts additional options, such as custom headers
let opts = Network.Wreq.defaults & Network.Wreq.auth ?~ Network.Wreq.basicAuth "user" "pass" Friendships friends <- post sess (newFriendRpc user) user2 mapM_ (print . userID) friends
deleteWith :: FromJSON a => Options -> Session -> Ref a -> IO a Source #
Sends as DELETE request to an API endpoint that responds in the JSON format. This function excepts additional options, such as custom headers
let opts = Network.Wreq.defaults & Network.Wreq.auth ?~ Network.Wreq.basicAuth "user" "pass" Status { success } <- deleteWith opts sess usersDeleteRef
Utility functions
Orphan instances
Postable () Source # | Some API endpoints are odd in that they expect a POST as a verb, but no request body is expected. This models such case. |
Postable [(Text, Text)] Source # | The form attributes are passed as tuples, representing key-value pairs: For example postPayload [("username", "jon"), ("password", "snow")] |