Metamug XRequest

XRequest (External Request) allows the developer to make an HTTP request to external (3rd party) APIs. The <XRequest> tag can be placed anywhere inside the <Request> tag.

<Request method="GET">
    <Query when="$q eq 1">
        SELECT * FROM movie
    </Query>
    <XRequest id="testReq1" when="$q eq 2" url="http://localhost:7000/testx/v1.1/movies"
                      method="GET" verbose="true">
        <Header name="Accept" value="application/json" />                
    </XRequest>
</Request>

Attributes

  1. id Used for uniquely identifying the XRequest
  2. url Represents the url endpoint to which the HTTP request is to be made
  3. method The HTTP method (GET/POST/PUT/DELETE)
  4. verbose Boolean determining whether the response is to be returned (TRUE/FALSE)
  5. persist Boolean determining whether the response can be accessed by the next tag (TRUE/FALSE)

Header and Param tags

<Header> tags represent the headers to be sent in the request. <Param> tags are used for sending query params in the request. Both of these tags are to be used inside the <XRequest> tag and have only two attributes

  1. name Represents name of the Header/Param
  2. value Represents its value
<XRequest id="testReq2" url="http://localhost:7000/testx/v1.1/movies"
                method="POST" verbose="true" persist="false" >
    <Header name="Content-Type" value="application/x-www-urlencoded"/>
    <Param name="movie" value="The Godfather" />
    <Param name="rating" value="4" />
</XRequest>  

When making post request with params, it is necessary to use Header Content-Type: application/x-www-urlencoded.

Body tag

<Body> can also be used inside <XRequest> representing the exact request body to be sent. This is helpful when making requests with json body.

Example POST request with JSON

<XRequest id="testReq2" url="http://localhost:7000/testx/v1.1/movies"
                method="POST" verbose="true" persist="false" >
    <Header name="Content-Type" value="application/json"/>
    <Body>
        {  
            "p": "The Godfather",
            "q": "4"   
        }
    </Body>
</XRequest>


Example PUT Request with JSON body

<XRequest when="$q eq 5" id="testReq4" url="http://localhost:7000/testx/v1.1/movies/20"
                 method="PUT" verbose="true" persist="false" >  
    <Header name="Content-Type" value="application/json"/> 
    <Body>
        {  
            "rating": "3"   
        }
    </Body>            
</XRequest>   


Example DELETE Request

<XRequest id="testReq3" url="http://localhost:7000/testx/v1.1/movies/3"
                 method="DELETE" verbose="true" persist="false" >               
</XRequest>


Note The HTTP methods used for <Request> and <XRequest> are independent of each other.

Request Parameters in XRequest

Request parameters can be accessed inside XRequest by using the $ symbol. The following example shows the parameters title and body being used inside the XRequest body.

<Request method="POST">
    <XRequest id="ExampleRequest" url="https://fcm.googleapis.com/fcm/send"
                  method="POST" verbose="true">
        <Header name="Content-Type" value="application/json"/> 
        <Body>
            {
                "notification": {
                    "title": "$title",
                    "body": "$body"
                }
            }
        </Body> 
    </XRequest>
</Request>

XRequest Output

The response received by the XRequest consists of the response body and response status code. The response format (json/xml) will be decided by the Accept header value. In case of an error, the message will be contained in the response body.

Let's make XRequest to https://jsonplaceholder.typicode.com/todos/1

<Request method="GET">
    <Desc> Example XRequest persist </Desc>
    <XRequest id="testXReq" url="https://jsonplaceholder.typicode.com/todos/1"
                  method="GET" verbose="true">
    </XRequest>
</Request>

The output of the above Request looks as follows

[
    {
        "body": {"id": 3, "completed": false, "title": "fugiat veniam minus", "userId": 1},
        "statusCode": 200
    }
]

statusCode holds the HTTP status code received from the API and body consists of the actual payload.

Persist in XRequest

The response returned by XRequest can be persisted and used in succeeding components. Persist feature in XRequest is only available for json response.

Let's make an XRequest to the above API and persist the response as follows

<Request method="GET">
    <Desc> Example XRequest persist </Desc>
    <XRequest id="testXReq" url="https://jsonplaceholder.typicode.com/todos/1"
                  method="GET" verbose="false" persist="true" >
    </XRequest>
    <Query>SELECT $testXReq.body.title AS `persistedValue`</Query>
</Request>

As we can see, the value of title from the response body is accessed in the succeeding Query. This is done by using dot-notation ({xrequestId}.{body}.{keyname}). Hence, the persist variable is $testXReq.body.title.

The output of the above GET request looks like

[
    {
        "persistedValue": "fugiat veniam minus"
    }
]


Values from json array response can also be accessed using dot-notation. The API https://jsonplaceholder.typicode.com/todos returns a json array as follows

[
    {
        "userId": 1,
        "id": 1,
        "title": "delectus aut autem",
        "completed": false
    },
    {
        "userId": 1,
        "id": 2,
        "title": "quis ut nam facilis et officia qui",
        "completed": false
    },
    {
        "userId": 1,
        "id": 3,
        "title": "fugiat veniam minus",
        "completed": false
    },
    {
        "userId": 1,
        "id": 4,
        "title": "et porro tempora",
        "completed": true
    },
    .
    .
    .
]

The above API can be called using XRequest

<Request method="GET">
    <Desc> Example Xrequest array </Desc>
    <XRequest id="testReq" url="https://jsonplaceholder.typicode.com/todos"
                  method="GET" verbose="false" persist="true" ></XRequest>

    <Query>SELECT $testReq.body[2].title AS `valueFromArray`</Query>
</Request>

The output is as follows

[
    {
        "valueFromArray": "fugiat veniam minus"
    }
]