Request

The Request Javascript module provides a mechanism for an add-on rendered in an iframe to make an XMLHttpRequest to the host product without requiring CORS.

In contrast to REST calls made from the add-on server to the product directly, any requests made in the browser are evaluated in the context of the currently logged in user. The requested resource is still evaluated against the add-ons granted scopes.

Example

1
2
3
4
5
AP.request('/rest/api/latest/...', {
  success: function(responseText){
    alert(responseText);
  }
});

Methods

addRequestMarshal ()

allows for dynamic rejection of ajax requests before they can be invoked. eg: by checking against a whitelist

request (url, options)

Execute an XMLHttpRequest as a Promise, or via callbacks, in the context of the host application. The format of the response (dataType) will be set to "text" as default; however, if binary data is requested, it will be set to "arraybuffer".

Parameters

NameTypeDescription
urlString

Either the URI to request or an options object (as below) containing at least a 'url' property;
This value should be relative to the context path of the host application.

optionsObject

The options of the request.

Properties
NameTypeDefaultDescription
urlString

The url to request from the host application, relative to the host's context path

typeStringGET

The HTTP method name.

cacheBooleantrue

If the request should be cached.

data[String Object]

The body of the request; required if type is 'POST' or 'PUT'. Optionally, for 'GET' this will append the object as key=value pairs to the end of the URL query string.

contentTypeString

The content-type string value of the entity body, above; required when data is supplied.

headersObject

An object containing headers to set; supported headers are: 'Accept', 'If-Match' and 'If-None-Match'.

successfunction

An optional callback function executed on a 200 success status code.

errorfunction

An optional callback function executed when a HTTP status error code is returned.

experimentalBooleanfalse

If this is set to true, the developer acknowledges that the API endpoint which is being called may be in beta state, and thus may also have a shorter deprecation cycle than stable APIs.

binaryAttachmentBooleanfalse

If this is set to true, the developer is specifying a request for an attachment consisting of binary data (e.g. an image) and the format of the response will be set to "arraybuffer".

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// A simple POST request which logs response in the console.
AP.request({
  url: '/rest/api/latest/...',
  type: 'POST',
  data: {name: 'some text', description: 'test'},
  success: function(responseText){
    console.log(responseText);
  },
  error: function(xhr, statusText, errorThrown){
    console.log(arguments);
  }
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Upload an attachment to a Confluence entity.
var fileToUpload = document.getElementById("fileInput").files[0];

AP.request({
  url: '/rest/api/content/123456/child/attachment',
  type: 'POST',
  contentType: 'multipart/form-data',
  data: {comment: 'example comment', file: fileToUpload},
  success: function(responseText){
    alert(responseText);
  }
});

1
2
3
4
5
// Get the current user info using a Promise

AP.request('/rest/api/user/current')
  .then(data => alert(data.body))
  .catch(e => alert(e.err));