Defining Custom Function Actions

A custom function action is the server-side code that runs when the endpoint is called. This article shows how to define one, with patterns for validation, error handling and response shaping.

Anatomy of an Action

An action receives a request object with parsed body, path parameters, query parameters and the authenticated identity. It returns a structured response (data + status). The platform handles serialisation.

Step-by-Step Definition

1. Open Architect Panel → Custom API Functions and click New Function.
2. Pick HTTP method and path.
3. Declare required scopes and authentication mode.
4. Define expected input parameters and types (used for auto-validation).
5. Write the action body. Use the platform's helpers: $AM->db->query(...), $AM->notify(...), $AM->respond(...).
6. Test using the side-panel test runner.
7. Publish.

Response Shape

Consistency matters. Use the platform's respond() helper:

• respond($data, 200) — successful read/create.
• respond(null, 204) — successful delete.
• respond(['error' => 'message'], 400) — bad input.
• respond(['error' => 'not found'], 404) — missing entity.
• respond(['error' => 'forbidden'], 403) — caller lacks scope.

Error Handling

• Catch known business errors and return 4xx with descriptive messages.
• Let unexpected exceptions bubble — the platform's error handler logs and returns 500 with an opaque error ID.
• Log warnings to the per-client audit log so support can investigate calls later.

Worked Examples

• Recalculate order: Validate caller has scope, load order, run pricing engine, save, return new totals.
• Bulk discount: Validate input array, paginate updates in transactions of 100 to avoid lock contention, return summary { updated: 947, skipped: 53 }.
• Send notifications: Validate template exists, resolve recipients, queue notifications, respond with the queued count.