GET API

The api.get(url) method is used to perform a GET request to an external API and fetch data. This is the most common pattern for real-time data retrieval in personalization and dynamic content use cases.

Syntax

var res = api.get(url);

Method Description

Note: Either .invoke() or .invokeForJson() must be called at the end of the request chain.

Function Example

Example: Fetching Products by Category and Status

This script demonstrates a typical retail scenario: dynamically retrieving product data by category and status for use in a personalized campaign or content block.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Fetches filtered product data based on category and status.
function getProductData_main(category, status) {
  var output = [];
  
  // Build the API URL using the function parameters
  var apiUrl = "https://api.example.com/products"
             + "?category=" + encodeURIComponent(category)
             + "&status=" + encodeURIComponent(status);

  try {
    // Fetch products matching the category and status
    var apiResponse = api.get(apiUrl)
      .putHeader("Accept", "application/json")
      .enableCache(60)
      .invokeForJson();

    // Extract products array from the API response if present
    output = apiResponse.json && apiResponse.json.products
      ? apiResponse.json.products
      : [];
  } catch (error) {
    // Log the error if the API call fails
    console.log("[getProductData_main] API call failed:", error);
  }

  console.log("[getProductData_main] Output:", output);
  return output;
}

• Calls the API endpoint https://api.example.com/products, using category and status as dynamic query parameters (these could be any business-relevant filters).

• Sets the Accept: application/json header and enables caching for 60 minutes.

• Parses the API response as JSON and extracts the products array.

• Returns the filtered product list as the output.

• Input arguments are fully dynamic and can be changed for your use case.

• Stores the output in the res object for further processing.

Note: The function arguments (here: category, status) are placeholders, adapt them to your actual API requirements, such as user ID, date, location, etc.

Handling API Responses

When working with external APIs, CodeFusion supports two main invocation methods:

• .invoke() for raw (string) responses

• .invokeForJson() for structured JSON responses

Understanding the structure and handling of each type ensures your scripts remain robust and your business logic is reliable.

Success Response Example:

A typical success response using .invokeForJson():

1
2
3
4
5
6
7
8
9
10
{
  "apidata": {
    "rawResponse": "{\"rcs\":\"eF5j4cotK8lME\"}",
    "json": {
      "rcs": "eF5j4cotK8lME"
    },
    "responseCode": 200
  }
}

Note: If you use .invoke() with .putHeader("Accept", "application/json"), the json property is also available—provided the API returns a valid JSON response.

Response Behavior Based on Invocation Method

Example: Raw Response with .invoke()

1
2
3
4
5
6
7
8
9
10
{
  "apidata": {
    "rawResponse": "{\"token\":\"0bdade22744ae00\"}",
    "json": {
      "token": "0bdade22744ae00"
    },
    "responseCode": 200
  }
}

Example: JSON Response with .invokeForJson()

1
2
3
4
5
6
7
8
9
10
{
  "apidata": {
    "rawResponse": "{\"token\":\"0bdade22744ae00\"}",
    "json": {
      "token": "0bdade22744ae00"
    },
    "responseCode": 200
  }
}

Key Attributes in API Response

• rawResponse: The raw API response body as a string, regardless of content type.

• json: The parsed JSON object from the response.

  Available when using .invokeForJson(), or when using .invoke() with .putHeader("Accept", "application/json") and the API returns valid JSON.

• responseCode: The HTTP status code, such as 200 (success), 400 (bad request), or 401 (unauthorized).

• status: (in some APIs) This property typically matches the HTTP response code.

Tip: For most scenarios, use .invokeForJson() so you can easily access response fields in your script. Use .invoke() if you need to handle non-JSON or custom formats, and always add .putHeader("Accept", "application/json") if you expect a JSON response.