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 -> Maybe AccessToken -> ByteString -> [(ByteString, Maybe ByteString)] -> Endo Request -> Handler b Connect (Either ProductErrorResponse (Maybe 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 -> Maybe AccessToken -> 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 Nothing "/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 -> Maybe AccessToken -> ByteString -> [(ByteString, Maybe ByteString)] -> Endo Request -> Handler b Connect (Either ProductErrorResponse a)

This is a convinience method that calls hostRequest as a POST method and requires that the resource returns content.

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

This is the same method as hostPostRequest except that if HTTP 204 No Content is returned then you will get nothing instead of an error.

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

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

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

This is the same method as hostPutRequest except that if HTTP 204 No Content is returned then you will get nothing instead of an error.

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

Methods

minBound :: StdMethod

maxBound :: StdMethod

Enum StdMethod

Methods

succ :: StdMethod -> StdMethod

pred :: StdMethod -> StdMethod

toEnum :: Int -> StdMethod

fromEnum :: StdMethod -> Int

enumFrom :: StdMethod -> [StdMethod]

enumFromThen :: StdMethod -> StdMethod -> [StdMethod]

enumFromTo :: StdMethod -> StdMethod -> [StdMethod]

enumFromThenTo :: StdMethod -> StdMethod -> StdMethod -> [StdMethod]

Eq StdMethod

Methods

(==) :: StdMethod -> StdMethod -> Bool

(/=) :: StdMethod -> StdMethod -> Bool

Ord StdMethod

Methods

compare :: StdMethod -> StdMethod -> Ordering

(<) :: StdMethod -> StdMethod -> Bool

(<=) :: StdMethod -> StdMethod -> Bool

(>) :: StdMethod -> StdMethod -> Bool

(>=) :: StdMethod -> StdMethod -> Bool

max :: StdMethod -> StdMethod -> StdMethod

min :: StdMethod -> StdMethod -> StdMethod

Read StdMethod

Methods

readsPrec :: Int -> ReadS StdMethod

readList :: ReadS [StdMethod]

readPrec :: ReadPrec StdMethod

readListPrec :: ReadPrec [StdMethod]

Show StdMethod

Methods

showsPrec :: Int -> StdMethod -> ShowS

show :: StdMethod -> String

showList :: [StdMethod] -> ShowS

Ix StdMethod

Methods

range :: (StdMethod, StdMethod) -> [StdMethod]

index :: (StdMethod, StdMethod) -> StdMethod -> Int

unsafeIndex :: (StdMethod, StdMethod) -> StdMethod -> Int

inRange :: (StdMethod, StdMethod) -> StdMethod -> Bool

rangeSize :: (StdMethod, StdMethod) -> Int

unsafeRangeSize :: (StdMethod, StdMethod) -> Int

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

Methods

showsPrec :: Int -> ProductErrorResponse -> ShowS

show :: ProductErrorResponse -> String

showList :: [ProductErrorResponse] -> ShowS

Generic ProductErrorResponse

Associated Types

type Rep ProductErrorResponse :: * -> *

Methods

from :: ProductErrorResponse -> Rep ProductErrorResponse x

to :: Rep ProductErrorResponse x -> ProductErrorResponse

type Rep ProductErrorResponse

type Rep ProductErrorResponse

Request Modifiers

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

Add a request headers.

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

setQueryParams :: [(ByteString, Maybe ByteString)] -> RequestTransformer

Set request query parameters.

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.