---
title: "callRest"
canonical: "https://support.appfire.com/space/JMWEC/465242995/callRest"
format: markdown
---
> Macro (aura-html)

## Applies to

A string representing the REST API endpoint to call. For example `"https://reqres.in/api/users"`. Note it can also be another Jira instance like `https://example.atlassian.net/`

## Parameters

Note the use of named parameters instead of positional parameters because of the number of parameters and their optional nature. 

| **Named parameter** | **Description** | **Examples** |
| --- | --- | --- |
| `verb` | Indicates the HTTP verb such as GET (to get information), PUT (to update existing information), POST (to post or create a new item), DELETE (to delete an item).<br>The default is `GET`.<br>> ℹ️ The verb is not case-sensitive. | - `{{ "https://reqres.in/api/users" | callRest() | dump(2)}} ` dumps all the users in a pretty JSON format<br>updates the first name of the user whose id is `1`<br>creates a new user in the rest API<br>- `{{ "https://reqres.in/api/users/12" | callRest(verb="delete") | dump(2)}}` deletes the user with id 12 |
| `params` | Indicates the parameters to be passed to replace placeholders in the rest-url. It is a hash of key and values. Any instance of ":key" in the `rest-url` is replaced with its value found in the hash under "key". The value will be Uri-Encoded.<br>The default is no param | `{{ "https://reqres.in/api/users/:id" | callRest(params={"id":"11"}) | dump(2)}}` dumps the information of the user with id 11. |
| `query` | Indicates the query parameters to be added to the http call. It is a hash of key and values. The values must be scalar and will be encoded appropriately. This is used to return a subset of fields.<br>The default is no query param. | `{{ "https://reqres.in/api/users" | callRest(verb= "GET",query={"id":"2"}) | dump(2)}}` will call `https://reqres.in/api/users?id=2` and dump the information of the user with the id `2`. |
| `body` | Indicates the body to pass to `PUT` and `POST` calls. It is an object that will be automatically converted to JSON.<br>The default is no body. | ```
{{ "https://reqres.in/api/users" | callRest( verb="post",
body={
    "name": "morpheus",
    "job": "leader"
}) }}
```<br>creates a new user in the API with the information provided in the body |
| `options` | Indicates the options passed to the "request" call. Often this is used to pass authentication information (see the example at right) but many other options are supported (see [this section](https://www.npmjs.com/package/request#requestoptions-callback) for the entire list).<br>The default is no options.<br>> 📝 Timeout duration can be set here. Value is set in milliseconds, with a default value of 20s and a maximum timeout of 3 minutes. 
> 📝 
> 📝 Use the format: 
> 📝 
> 📝 `options = { timeout: 120000; } `
> 📝 
> 📝 Where ‘120000’ is 2 minutes.<br>> ⚠️ When using the [Nunjucks Template Tester](https://appfire.atlassian.net/wiki/spaces/JMWEC/pages/465373737), the **maximum **timeout value is 20 seconds! | The following code dumps the data for the issue with key TEST-1, operating with the provided authentication information set in `auth` within `options`.<br>```javascript
{{ "https://example.atlassian.net/rest/api/2/issue/TEST-1" | callRest(
options = { "auth": 
  {"username" : "abc@example.com",
    "password": "sdfuhsdlsle9t739875983" 
  }
})
| dump(2)}}
```<br>To send parameters as `application/x-www-form-urlencoded` use the following options:<br>```
{{ "https://reqres.in/get_token_oauth" | callRest( verb="post",
options = { 
  headers: {
    "Accept": "*/*", 
    "Content-type": "application/x-www-form-urlencoded"
  } 
}, 
body={"grant_type": "client_credentials" }
)
}}
```<br>Body can either be in a form such as `param1=value1&param2=value2` or as JSON object.<br>To send multiple parameters using `multipart/form-data`, use the `form` option. This is particularly useful when there are too many parameters to include as query parameters.<br>```
{{ "https://xxxxxx.example.app/job/test_job/buildWithParameters" | callRest(
verb = "post", 
options = { 
  "auth": { 
    "username": "username", 
    "password": "xxxxx"
  }, "form": {
    "param1": "veryLongParameterValueWouldGoHere", 
    "param2": "anEvenLongerParameterValueCouldGoHere", 
    "param3": "theseParametersAreSoLongItWouldMaybeTriggerA414Error"}
  }
) | dump(2) }}
``` |
| `noJSON` | Controls the response format. If `true`, the response body will be returned *as is* instead of being parsed as JSON. Also, the *request* body will not be automatically converted to JSON.<br>The default is `false` | ```javascript
{{ "https://currency-exchange.p.rapidapi.com/listquotes" | 
callRest( options = {
    headers: {
      "x-rapidapi-host": "currency-exchange.p.rapidapi.com",
      "x-rapidapi-key": "89397d9ee7msh152cdc367c4c66fp16691ejsn9bb6a580e905"
    }
  },noJSON=true) | dump }}
```<br>dumps the response as plain text. |
| `dontFail` | If `true`, when the REST call returns an error, instead of throwing an exception, the error will be returned as an object containing an `_error` and/or a `_statusCode` field. | - `{{ "https://httpstat.us/404" | callRest(dontFail=true) | dump(2)}}`  returns: |
| `fixedIP` | > ⚠️ **Warning**: This parameter has been deprecated. Existing IP addresses will be ignored and AWS IP addresses (listed below) will be used instead. Functions using **callRest** that include a value for this parameter will log a warning to the [JMWE Logs](https://appfire.atlassian.net/wiki/spaces/JMWEC/pages/466321741).<br>If `true`, the REST call is made from a fixed static IP address, which users can then whitelist for security purposes.<br>The following IP addresses are used:<br>- 18.211.22.6
- 34.193.8.92<br>The default is `false` | ```
{{ "https://currency-exchange.p.rapidapi.com/listquotes" | 
callRest( options = {
    headers: {
      "x-rapidapi-host": "currency-exchange.p.rapidapi.com",
      "x-rapidapi-key": "89397d9ee7msh152cdc367c4c66fp16691ejsn9bb6a580e905"
    }
  },fixedIP=true) | dump }}
``` |

## Examples

Here are a few examples using the `callRest` filter

### Get the information from an API

```
{{ "https://reqres.in/api/users" | callRest(query={"id":"2"}) | dump(2)}} 
```

Gets** **the information of a user with id `2` and outputs the information in a pretty JSON format with 2 spaces indentation.

### Get issue information from another Jira instance

Using this filter you can make calls to another Jira instance. You will need to authenticate using the username (one used to log in to the instance) and password (the [API token ](https://confluence.atlassian.com/cloud/api-tokens-938839638.html)created for the destination instance).

```
{{ "https://example.atlassian.net/rest/api/2/issue/TEST-1" | callRest(
options = { "auth": 
  {"username" : "abc@example.com",
    "password": "sdfuhsdlsle9t739875983" 
  }
})
| dump(2)}}
```

dumps the details of the issue with key TEST-1 using the provided authentication information.

### Convert the amount in a custom field to a specific currency

```
{{ "https://currency-exchange.p.rapidapi.com/exchange" | 
 callRest( query={ "q": "1.0", "from": "USD", "to": "INR"},
  options = ( { headers: { 
   "x-rapidapi-host": "currency-exchange.p.rapidapi.com",
   "x-rapidapi-key": "89397d9ee7msh152cdc367c4c66fp16691ejsn9bb6a580e905" 
   } 
  } )
 ) * issue.fields.customfield_11507 }}
```

returns the amount in the custom field in INR currency.

### Use a callRest response in a template

In scenarios where the response from a REST API needs to be used in a template, use the `{% set %}` tag. For example: 

```
{% set response = "https://reqres.in/api/users" | callRest(query={"id":"2"}) | dump(2) 
%}
{{ response }}
{# remainder of template #}
```