Snap.AtlassianConnect.HostRequest

While writing Atlassian Connect applications you will often be in a situation where you want to query the Host Application directly in a trusted way. This may be because:

• You are not making this request on behalf of a user. You are making it on behalf of your Addon. (Data ingestion etc.)
• You cannot trust the information that the Customer has given you. For example: don't trust the customer to tell you if they are an admin or not. Go directly to the Host application for that.

This module allows you to make HTTP requests to the host application and expect JSON responses. There are convinience methods for GET, POST and PUT requests which make up the majority of the requests that you are going to make.

It is important to note that these requests are still restricted by the scopes that you have asked for in your Atlassian Connect Descriptor.

For an example of usage: look at the httpGetRequest function.

Host (Product) Request Helpers

hostRequest :: FromJSON a => StdMethod -> Tenant -> ByteString -> [(ByteString, Maybe ByteString)] -> Endo Request -> Handler b Connect (Either ProductErrorResponse a)

As an Atlassian Connect application you will want to make requests of the Host Applicaiton (JIRA / Confluence) so that you can get important information. This function lets you do so by doing most of the heavy lifting of having to create a JWT token and a Query String Hash. It also asserts that you intended to get a JSON response. You should use this method or the helper methods whenever you want to make requests of the host application.

hostGetRequest :: FromJSON a => Tenant -> ByteString -> [(ByteString, Maybe ByteString)] -> Endo Request -> Handler b Connect (Either ProductErrorResponse a)

This is a convinience method that calls hostRequest as a GET method.

Here is an example of it being used to make a call for user details:

jiraUserDetailsResponse <- hostGetRequest myConnectTenant "/rest/api/2/user" [("username", Just "admin")] mempty

This example assumes that you are using the OverloadedStrings LANGUAGE pragma and that you don't need to modify the request. You might want to might want to modify the request for multiple reasons. Too add proxy details for example.

hostPostRequest :: FromJSON a => Tenant -> ByteString -> [(ByteString, Maybe ByteString)] -> Endo Request -> Handler b Connect (Either ProductErrorResponse a)

This is a convinience method that calls hostRequest as a POST method.

hostPutRequest :: FromJSON a => Tenant -> ByteString -> [(ByteString, Maybe ByteString)] -> Endo Request -> Handler b Connect (Either ProductErrorResponse a)

This is a convinience method that calls hostRequest as a PUT method.

data StdMethod :: *

HTTP standard method (as defined by RFC 2616, and PATCH which is defined by RFC 5789).

Constructors

GET

POST

HEAD

PUT

DELETE

TRACE

CONNECT

OPTIONS

PATCH

Instances

Bounded StdMethod

Enum StdMethod

Eq StdMethod

Ord StdMethod

Read StdMethod

Show StdMethod

Ix StdMethod

data ProductErrorResponse

If you fail to properly communicate with the Host application then you will get a product error response back.

Constructors

ProductErrorResponse

Fields

perCode :: HttpResponseCode

The HTTP error code.

perMessage :: Text

The error message.

Instances

Show ProductErrorResponse

Generic ProductErrorResponse

type Rep ProductErrorResponse

Request Modifiers

addHeader :: (CI ByteString, ByteString) -> RequestTransformer

Add a request headers.

setPostParams :: [(ByteString, ByteString)] -> Endo Request

setBody :: ByteString -> RequestTransformer

Set the request body from the specified byte string.

setBodyLazy :: ByteString -> RequestTransformer

Set the request body from the specified lazy byte string.

setJson :: ToJSON a => a -> RequestTransformer

Set the request body from the value which can be converted to JSON.