Functions (UDFs) API Overview

The Informer Functions API provides endpoints for creating and managing User-Defined Functions (UDFs). UDFs are custom JavaScript functions that can be used in queries, datasets, and reports to extend Informer's built-in functionality. All routes are prefixed with /api.

Features

• Custom Functions - Write JavaScript functions for data transformation
• Namespacing - Organize functions by namespace
• Parameters - Define function parameters with validation
• Testing - Validate function syntax before saving
• Reusable - Use functions across queries, datasets, and reports

Function Structure

A function consists of:

• namespace - Organizational namespace (e.g., custom, math, text)
• name - Function name (used when calling)
• script - JavaScript function body
• params - Array of parameter definitions
• description - Optional description of function purpose

Authentication

All Function API endpoints require authentication via session cookies or API tokens. Creating, updating, and deleting functions requires appropriate permissions.

Endpoints

GET /api/functions

Get a list of all user-defined functions.

Authentication: Required (session)

Response:

[
  {
    "id": "func-123",
    "namespace": "custom",
    "name": "formatCurrency",
    "description": "Format number as currency",
    "script": "function(value) { return '$' + parseFloat(value).toFixed(2); }",
    "params": [
      {
        "name": "value",
        "type": "number",
        "description": "Value to format"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "func-456",
    "namespace": "math",
    "name": "average",
    "description": "Calculate average of array",
    "script": "function(arr) { return arr.reduce((a,b) => a+b, 0) / arr.length; }",
    "params": [
      {
        "name": "arr",
        "type": "array",
        "description": "Array of numbers"
      }
    ],
    "createdAt": "2024-01-14T14:22:00Z",
    "updatedAt": "2024-01-14T14:22:00Z"
  }
]

---

POST /api/functions

Create a new user-defined function.

Authentication: Required (session)

Pre-blocks: permission.functions.create, function.validate(payload)

Request Body:

Field	Type	Required	Description
namespace	string	Yes	Function namespace
name	string	Yes	Function name
script	string	Yes	JavaScript function body
params	array	No	Array of parameter definitions
description	string	No	Function description (null or empty allowed)

Parameter Definition Object:

Field	Type	Description
name	string	Parameter name
type	string	Parameter type (number, string, array, object, etc.)
description	string	Parameter description
required	boolean	Whether parameter is required
default	any	Default value if not provided

Example Request:

{
  "namespace": "custom",
  "name": "formatPhone",
  "description": "Format US phone number",
  "script": "function(phone) { const cleaned = ('' + phone).replace(/\\D/g, ''); const match = cleaned.match(/^(\\d{3})(\\d{3})(\\d{4})$/); if (match) { return '(' + match[1] + ') ' + match[2] + '-' + match[3]; } return phone; }",
  "params": [
    {
      "name": "phone",
      "type": "string",
      "description": "Phone number to format",
      "required": true
    }
  ]
}

Response:

Returns the created function object with 201 Created status and Location header.

{
  "id": "func-789",
  "namespace": "custom",
  "name": "formatPhone",
  "description": "Format US phone number",
  "script": "function(phone) { ... }",
  "params": [
    {
      "name": "phone",
      "type": "string",
      "description": "Phone number to format",
      "required": true
    }
  ],
  "createdAt": "2024-01-15T14:22:00Z",
  "updatedAt": "2024-01-15T14:22:00Z"
}

Validation:

• Function script is validated for syntax errors before saving
• Function is executed in a sandbox environment
• Invalid JavaScript will result in 400 error

---

POST /api/functions/_test

Test a function definition without saving it.

Authentication: Required (session)

Pre-blocks: function.validate(payload)

Request Body:

Same as POST /api/functions but doesn't persist the function.

Example Request:

{
  "namespace": "math",
  "name": "square",
  "script": "function(x) { return x * x; }",
  "params": [
    {
      "name": "x",
      "type": "number"
    }
  ]
}

Response:

{
  "result": true
}

Returns { result: true } if function is valid, or throws validation error if invalid.

---

GET /api/functions/{id}

Get a specific function by ID.

Authentication: Required (session)

Response:

{
  "id": "func-123",
  "namespace": "custom",
  "name": "formatCurrency",
  "description": "Format number as currency",
  "script": "function(value) { return '$' + parseFloat(value).toFixed(2); }",
  "params": [
    {
      "name": "value",
      "type": "number",
      "description": "Value to format"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "_links": {
    "self": { "href": "/api/functions/func-123" }
  }
}

Errors:

• 404 - Function not found

---

PUT /api/functions/{id}

Update a function.

Authentication: Required (session)

Pre-blocks: permission.function.edit, function.lookup(params.id)

Request Body:

Field	Type	Description
namespace	string	Function namespace
name	string	Function name
description	string	Function description (null or empty allowed)
script	string	JavaScript function body
params	array	Array of parameter definitions

Example Request:

{
  "description": "Format number as USD currency with symbol",
  "script": "function(value) { return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value); }"
}

Response:

Returns the updated function object.

Validation:

• Function is tested with new configuration before saving
• Invalid JavaScript will result in 400 error
• Changes are persisted only if validation passes

---

DELETE /api/functions/{id}

Delete a function.

Authentication: Required (session)

Pre-blocks: permission.function.delete

Response:

Returns 204 No Content on successful deletion.

---

Usage in Queries

Functions can be used in dataset queries and reports:

// In a query transformation
SELECT
  custom.formatCurrency(revenue) as formatted_revenue,
  custom.formatPhone(phone_number) as formatted_phone
FROM sales_data

Function Namespaces

Common namespaces:

• custom - User-defined custom functions
• math - Mathematical operations
• text - String manipulation
• date - Date/time operations
• array - Array operations

Security

• Functions execute in a sandboxed environment
• Access to Node.js built-in modules is restricted
• Functions cannot make network requests
• File system access is prohibited

Best Practices

• Use descriptive names and namespaces
• Document parameters with clear descriptions
• Test functions before saving with POST /api/functions/_test
• Keep functions focused on a single purpose
• Handle edge cases (null, undefined, empty values)