Scripting

Add logic to your API with server-side scripting

Scripts can be written using Groovy language and referenced inside resource files. The Console provides an editor for editing and saving Groovy script files.

Console Editor

Referencing Script files in Resources

Let's create a script file and save it with the name hello as follows:

hello.groovy

response['message'] = 'Hello World';

This file can be referenced in the resource XML using a <Script> tag as follows:

script.xml

<Request method="GET">
    <Script file="hello" id="firstscript" output="true"/>
</Request>

Response array

When we make a GET request to the script resource given above, the output obtained as follows:

{
   "firstscript": {
      "message":"Hello World"
    }
}

Here, we can observer that the values assigned to the response array in the script are printed in the response output.

Executing functions

Groovy scripts can be used to create functions. Below is a simple factorial function example.

def fact(n){
    if(n < 1)
        return 1;
    else
        return fact(n-1)*n;
}

response["output"]=fact(5)

Note here print will not work, like a regular script. The function call must be passed to response object.

Accessing Request parameters

All the request variables can be accessed with _$variable. If the variable is not present in the incoming the request you will get the following error

response["message"] = 'Hello ' + _$name;

Internal Elements with MPath

In order to access internal elements of the request using MPath. The MPath notation is used.

def sqlOutput = _$["sqlElement"].rows[2].name

Adding Script to Resource

In order to add a script to your request flow. The script needs to be added as an element inside Request tag.

Resource XML

hello.xml

<Request method="GET">
    <Desc> Greet with Hello </Desc>
    <Script id="msg" file="greet.groovy" output="true" />
</Request>

greet.groovy

response['msg'] = 'Hello ' + _$name;

The name needs to be passed as a query parameter in case of a GET request

/script?name=John

The response object is converted into a json object. In this example, msg is assigned with the greeting message

{ "script": { "msg": "Hello John" } }

Query to Script

One of the regular use-cases of scripts can be post-processing an SQL Result. Groovy has access to all the previous elements defined in the request with MPath.

qrytoscript.xml

<Request method="GET">  
    <Sql id="q"> SELECT * from movie </Sql>
    <Script id="greet" file="qtos.groovy" output="true" />
</Request>

qtos.groovy

we can use _$[“q“].rows[2].name to access the name attribute.

response['message'] = 'Hello ' +  _$["q"].rows[2].name;

Since the query element q is a request element, no parameter is expected in the GET request.

/qrytoscript

The above request will result in following response

{ 
  "q": [
    {"name":"Superman","rating":2,"id":1},
    {"name":"Spiderman","rating":4,"id":2},
    {"name":"Batman","rating":4,"id":5},
    {"name":"I am legend","rating":5,"id":8}
  ],
  "greet": {"message":"Hello Batman"}
}

3. XRequest to Script

When integrating external APIs, scripts can help add additional processing. No need to upload projects or write extensive code. Formatting, conversion between APIs can be easily handled with scripting.

xreqtoscript.xml

In the below request we have added a script tag after the XRequest.

<Request method="GET">
    <XRequest id="xreq" url="https://postman-echo.com/get?foo1=Hello&amp;foo2=World"
                          method="GET" output="true" >
        <Header name="Accept" value="application/json" />
    </XRequest>
    <Script id="greet" file="xtos.groovy" output="true"/>
</Request>

xtos.groovy

Here since the returned object is a JSON object we use getJSONObject method to access the element.

response['message'] = 'Hello ' + _$['xreq'].getJSONObject('args').getString('foo2');

Request and Response

/xreqtoscript

{
   "xreq": {

     "args": {"foo1":"Hello","foo2":"World"},
     "headers": {"x-forwarded-proto":"https","host":"postman-echo.com","x-forwarded-port":"443","accept-encoding":"gzip","accept":"application/json","user-agent":"okhttp/3.10.0"},

     "url":"https://postman-echo.com/get?foo1=Hello&foo2=World"
   },

   "greet": { "message": "Hello World" }
}

Using MPath to access Script Output

In the resource XML, standard MPath notation can be used to access script output. In case we want to access script information in a query or XRequest tag.

The below section must be added to MPath documentation

Script to Query

scripttoqry.xml

<Request method="GET">
    <Script id="script" file="test.groovy" output="true" />
    <Sql id="q"> SELECT $[script].message as greeting </Sql>
</Request>

test.groovy

response['message'] = 'Hello ' + _$name;

Sending the below request will result in the following response.

/scripttoqry?name=John

{  
    "q": [ 
            {"greet":"Hello John"} 
        ],
    "script": {
        "message":"Hello John"
    }
}

Script to Xrequest

scripttoxreq.xml

<Request method="GET">
    <Script id="script" file="test.groovy" output="true" />
    <XRequest id="xreq" url="https://postman-echo.com/post"
                          method="POST" output="true" >
        <Header name="Content-Type" value="application/json" />
        <Body>
            {
                "foo1": "Welcome",
                "foo2": "$[script].message"
            }
        </Body>
    </XRequest>
</Request>