BeanShell API Element

Introduction

The BeanShell API Element plugin offers greater flexibility over the API Builder's response by allowing customization through a BeanShell script.

Prerequisite

The BeanShell API Element plugin requires API Builder installed on at least Joget DX Version 8.

Plugin Information

The published API endpoint is publicly accessible for GET and POST request methods.

When sending a successful response, your BeanShell script should return org.json.JSONObject that includes a data JSON key, which contains the primary data for the response payload.

The data JSON key may contain either org.json.JSONObject or org.json.JSONArray.

For a customized successful response, you will need to provide the code and data JSON keys.

When sending an error response, you may provide a custom error message using the message JSON key. The data JSON key will be ignored.

BeanShell API Element Properties

Fields to configure:

• Script ID: The API endpoint to publish
• Script: The BeanShell script to execute
• Short Description:  Description for the API endpoint
• Execute BeanShell Script on GET request: Check the box to allow public access using the GET request method
• Execute BeanShell Script on POST request: Check the box to allow public access using the POST request method

Getting Started

Send a successful response with data

import org.json.JSONArray;
import org.json.JSONObject;

JSONArray friends = new JSONArray();
friends.put(new JSONObject().put("id", 0).put("name", "Harmon Graham"));
friends.put(new JSONObject().put("id", 1).put("name", "Ora Kline"));
friends.put(new JSONObject().put("id", 2).put("name", "Milagros Irwin"));

// JSONObject containing "data" key is required
return new JSONObject().put("data", friends);

Send a success response with an empty payload

import org.json.JSONObject;

/*
* get the input from request parameters or body then delete data in database
* in this case, sending updated data back to consumer is not relevant
*/

JSONObject response = new JSONObject();
response.put("code", 204);              // set response header to "No Content"
response.put("data", new JSONObject()); // empty JSONObject is required

return response;

Send error response

import org.json.JSONObject;

/*
* logic to update data in database
* but friend "id" is not found either in request parameters or body
*/

JSONObject response = new JSONObject();
response.put("code", 422);                  // set header to "Unprocessable Content"
response.put("message", "id is required");  // add a custom error message
// "data" JSON key is not applicable

return response;

Expected Outcome

With the BeanShell script, you may send a customized API response, unlike other API Builder Elements, where the response payload is fixed and cannot be altered.
In a single API endpoint, you may define multiple different responses tailored to your business requirements.

Source Code and Plugin Download

1. You can find the latest release at the Joget Marketplace.
2. Upload the plugin to your Joget by navigating to Settings > Manage Plugins > Upload Plugin as admin.

Download sample app