Skip to main content

Transform in Definition

Boltic supports JavaScript-based transformations within API definitions, enabling dynamic manipulation of request and response data. Developers can customize and preprocess various components of an API request or response:

Each transform must be a JavaScript function (expressed as a string) that returns the modified data. This flexibility allows for sophisticated handling of parameters, secrets, or runtime conditions.

1. Request URL Transformation​

Use this to dynamically adjust the request URL, such as appending query parameters or altering path segments.

Example​

{
    "definition": {
        "method": "get",
        "url": "https://app.asana.com/api/1.0/users/",
        "headers": {
            "Accept": "application/json",
            "Authorization": "Bearer {{secrets.access_token}}"
        },
        "transform": {
            "url": "function transformURL() { const encodedURL = url + encodeURIComponent('{{parameters.email}}'); return encodedURL; } return transformURL();"
        },
        "response": {
            "output": "{{response.data}}",
            "error": {
                "message": "{{response.data.errors[0].message}}",
                "code": "{{response.status}}"
            }
        }
    }
}

2. Query Params Transformation​

Use this to dynamically construct or modify query parameters.

Example​

"transform": {
    "query_params": "const params = {}; if (parameters.filter) { params.filter = parameters.filter; } return params;"
}

3. Headers Transformation​

Use this to add or modify headers dynamically, such as adding timestamps or trace identifiers.

Example​

"transform": {
    "headers": "headers['x-trace-id'] = `${Date.now()}-${Math.random().toString(16).slice(2)}`; return headers;"
}

4. Body Transformation​

Use this to dynamically build or restructure the request body.

Example​

"definition": {
    "method": "get",
    "url": "https://api.hubapi.com/crm/v3/properties/contact",
    "headers": {
        "Authorization": "Bearer {{secrets.access_token}}"
    },
    "transform": {
        "output": "const typeMap = {text:'text',textarea:'textarea',dropdown:'select',auto_complete:'multitext',multi_select_dropdown:'multiselect',radio:'select',number:'number'};const result=output.map(ele=>{const newObj={name:ele.name,meta:{displayName:ele.label,displayType:ele.options&&ele.options.length>0?'select':'text',placeholder:`${ele.options&&ele.options.length>0?'Select':'Enter'} ${ele.label}`,validation:{required:ele.required_for_agents}}};if(ele.options&&ele.options.length>0){newObj.meta.htmlProps={allowDynamic:true};newObj.meta.options=ele.options.map(choice=>({label:choice.label||choice,value:choice.value||choice}));if(ele.type==='multi_select_dropdown'){newObj.meta.value=[];}}if(ele.default===false){newObj.prop='custom_field';}return newObj;}).filter(ele=>ele!==null);const custom_field={name:'custom_field',meta:{children:[],displayType:'object'}};const outputWithCustomField=result.reduce((acc,ele)=>{if(ele.prop==='custom_field'){custom_field.meta.children.push(ele);}else{acc.push(ele);}return acc;},[]);if(custom_field.meta.children.length>0){outputWithCustomField.push(custom_field);} return outputWithCustomField;"
    },
    "response": {
        "output": "{{response.data.results}}",
        "error": {
            "message": "{{response.data.message}}",
            "code": "{{response.status}}"
        }
    }
}

5. Output Transformation​

Use this to reshape the successful response data before sending it back to users.

Example​

"definition": {
    "method": "get",
    "url": "https://api.anthropic.com/v1/models",
    "headers": {
        "content-type": "application/json",
        "x-api-key": "{{secrets.api_token}}",
        "anthropic-version": "2023-06-01"
    },
    "response": {
        "output": "{{response.data}}",
        "error": {
            "message": "{{response.data.message}}",
            "code": "{{response.status}}"
        }
    },
    "transform": {
        "output": "const updatedOutput = output.data.map((model) => { return { name: model.display_name, id: model.id }; }); return updatedOutput;"
    }
}

6. Error Transformation​

Use this to customize error messages and structure for improved clarity.

Example​

"transform": {
    "error": "if (error.code === 401) { return { message: 'Unauthorized — please check your token', code: 401 }; } return error;"
}

Best Practices​

  • Always explicitly return a value from transformation functions.
  • Encapsulate complex logic clearly within functions ... { ... }; return ...(); for readability if needed.

Limitations​

  • Only JavaScript is currently supported.
  • Asynchronous operations (e.g., fetch, setTimeout) are not permitted.
  • Avoid circular references or direct mutations of input objects, as these can result in unexpected behavior.