Custom API Functions

Custom API functions let you expose your own business logic over the REST surface, without modifying the platform's core. They're how you add company-specific endpoints — bulk operations, aggregations, calculations, integrations — to the standard CRUD API.

What They Look Like

Each custom function is registered with:

• An HTTP method (GET, POST, PATCH, DELETE).
• A path under /api/custom/….
• Required scopes (which API clients/users can call it).
• Input validation (required fields, types).
• Server-side code that runs to produce the response.

Common Use Cases

• Bulk operations: Apply a discount to 1000 orders in one call.
• Aggregations: Return a custom-shaped report rather than separate field queries.
• Business workflows: Approve a record + send emails + update accounting system in one atomic transaction.
• External integrations: A custom endpoint that fans out to multiple external APIs.

Worked Examples

• POST /api/custom/orders/{id}/recalculate — recalculate the order's pricing after a config change.
• POST /api/custom/users/import — bulk-import users from a custom CSV format, mapping fields per the import contract.
• GET /api/custom/reports/monthly-revenue — return aggregated monthly revenue + breakdown by tier in a single response.
• POST /api/custom/notifications/blast — broadcast a notification to a filtered audience with custom merge logic.

Tip: Prefix custom paths with /api/custom/ so they never collide with future standard endpoints when the platform adds new ones.

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.