Skip to main content

Make/PUT API calls

Suhas Reddy
Updated

The API_PUT extension sends a PUT request to a REST API endpoint and returns the response body as a JSON string that can be stored in a Virtuoso variable.

This is useful when a journey needs to update an existing backend record, change API-managed test data, or verify that a PUT request correctly applies the values supplied in the request body.

Parameters:

  • url required, a string containing the REST API endpoint to call. Query parameters or path identifiers, such as a user ID, can be included directly in the URL when needed;
  • body required, a JSON string containing the PUT request payload. The extension parses this value with JSON.parse(body) before sending it;
  • headers optional, a JSON string containing request headers, such as authorization, tenant, or content-type headers. Leave it blank when no custom headers are required.

Note: The body and headers inputs must be valid JSON strings when supplied. Invalid JSON, a missing URL, a missing body, or a response rejected by the API will fail the extension step through doneError.

How to apply this to your journey

Use the extension in a journey by calling API_PUT with the URL and request body. Pass each value to the matching extension input using as url, as body, and optionally as headers.

Note: The extension returns JSON.stringify(data). Store the result in a variable and assert against the parsed response fields exposed by Virtuoso, such as $data.first_name.

API_PUT("https://reqres.in/api/users/2", '{"first_name":"John"}') returning $data
assert $data.first_name equals "John"
API_PUT("https://reqres.in/api/users/2", '{"first_name":"John", "access":"read"}', '{"Authorization":"Bearer example-token"}') returning $data
assert $data.access equals "read"

You can also pass variables into the extension when the endpoint, payload, or headers are created earlier in the journey.

API_PUT($apiUrl, $requestBody) returning $data
assert $data.first_name equals "John"
store value "https://reqres.in/api/users/2" in $apiUrl
store value "John" in $request.first_name
store value "read" in $request.access
API_PUT($apiUrl, $request) returning $data
assert $data.first_name equals "John"

Advanced API calls

Some APIs require custom request headers, such as authentication tokens, content type, tenant identifiers, or API-version headers. The API_PUT extension supports this through the optional headers input. Pass headers as a valid JSON string or as a Virtuoso variable that resolves to a JSON object/string.

Content type example:

store value '{"content-type":"application/json"}' in $contentTypeHeader
API_PUT("https://reqres.in/api/users/2", '{"first_name":"John"}', $contentTypeHeader) returning $data
assert $data.first_name equals "John"

Header authentication example, where the authentication token is already stored in $token:

store value ${'Bearer ' + $token} in $authenticationHeader.Authorization
API_PUT("https://reqres.in/api/users/2", '{"first_name":"John"}', $authenticationHeader) returning $data
assert $data.first_name equals "John"

Example output:

{
  "first_name": "John",
  "access": "read",
  "updatedAt": "2021-01-14T17:44:54.000Z"
}

This extension requires the following resources:

The extension should be configured as:

  • Run asynchronously: Yes
  • Scope: Global

Limitation: This extension depends on the configured Axios CDN resource, valid JSON input, the target API, and browser-context network behavior. Because it uses axios.put, requests can be affected by CORS policy, authentication requirements, expired tokens, API validation rules, rate limits, network restrictions, proxy rules, blocked CDN access, content security policy, and API schema changes. The source parses body and headers with JSON.parse, so malformed JSON fails before the request is completed. The extension sends the parsed payload as the second argument to axios.put and passes parsed headers as request configuration, so unsupported header names, missing content-type requirements, or server-specific PUT semantics can cause the API to reject the request. The response is returned as a JSON string through done(JSON.stringify(data)); large or sensitive responses may be stored in journey variables and logs, so avoid returning secrets or unnecessary PII. Async extension scripts must complete within Virtuoso's documented 120-second maximum execution window, and the step fails if done() or doneError() is not reached. Cross-browser note: This extension does not inspect the page DOM, but it runs in the browser or device selected for the journey execution and uses Axios' browser request behavior. Validate it in each browser/device configuration used by your plans, especially where CORS handling, network access, CDN loading, corporate proxies, or mobile/remote-grid connectivity may differ.

Add the extension to your Virtuoso instance

Select the domain that matches your Virtuoso account.

Add extension to Virtuoso - https://app.virtuoso.qa/ → Add extension to Virtuoso Free Trial - https://app2.virtuoso.qa/ →
Add extension to Virtuoso US - https://app-us.virtuoso.qa/ → Add extension to Virtuoso UK - https://app-uk.virtuoso.qa/ →
View source

Last updated: 14/01/2021

Resources:

// Last updated: 14/01/2021, 17:44:54 UTC
// Resources:
//   https://cdnjs.cloudflare.com/ajax/libs/axios/0.21.1/axios.min.js

const makeRequest = async (url, body, headers = '') => {
  try {
    const { data } = await axios.put(
        url,
        JSON.parse(body),
        headers ? {headers: JSON.parse(headers)} : {},
    )
    done(JSON.stringify(data))
  } catch (e) {
    doneError(e)
  }
}

if (!url) {
  throw new Error('URL parameter is missing')
}

if (!body) {
  throw new Error('body parameter is missing')
}

makeRequest(url, body, headers)

Comments

0 comments

Please sign in to leave a comment.