Common Blueprint Patterns

Copyable blueprint recipes for everyday tasks: form validation, API auth, data transformation, error handling, and caching with Redis and storage events.

Each pattern below is a mini-recipe you can copy straight onto your canvas: the goal, when to use it, the blocks involved with their wiring, and notes from practice. Every block mentioned exists in the current block library — search its type name in the blueprint editor to add it.

1. Form Validation

Goal: Reject incomplete submissions before they reach storage.

When to use: Any state page that accepts user input through a form and writes it to storage or passes it to a function.

Recipe:

Wire every required field of the form-object into its own condition_not_empty_value block. Only when all conditions pass does the flow continue to the create or update document blocks; otherwise it branches to an error message in the UI.

Notes:

• Validate before touching storage — a rejected submission should never produce a document.
• Keep one condition block per field instead of one combined check, so the UI can tell the user exactly which field failed.
• Inspect the form-error pin first: form-level errors mean the submitted data could not be read at all.

2. API Authentication

Goal: Expose an API endpoint only to the right callers, with explicit error replies for everyone else.

When to use: Any custom API built with an on_startup_register_uri_{method} block that should not be fully public.

Recipe:

With the *loggedin scope, the cluster rejects requests without a valid access_token before your flow runs. Inside the flow, user_current plus a condition on the user's scopes lets you add finer-grained checks and answer failures yourself through httpconnection_set_json.

Notes:

• Callers can pass the token five ways: Authorization: Bearer header, x-authtoken or x-token header, an access_token cookie, or the ?access_token= query parameter — see Adding tokens to your requests. Tokens are valid for 14 days and extend automatically while actively used (Token Expiry).
• Protect the endpoint further with a rate limit or throttle in a few clicks.
• An endpoint that still returns 404 after scoping usually was never activated — press Activate and deploy for production traffic. See API not activating.

3. Data Transformation

Goal: Turn storage documents into exactly the shape your API or UI needs — no more, no less.

When to use: Shaping API responses, converting arrays of documents, and writing denormalized data.

Recipe A — shape a response object: Feed the fields you want to expose into an object_new_fields (new object) block, which builds a fresh object containing only those fields. Use object_update_fields when you want to adjust an existing object instead of building a new one. This keeps internal fields such as _meta internals out of your API responses.

{
  "guid": "a23575f49d0af385314c1f02280163374297e018a692e5e4ab85eb307ebf6ebc",
  "username": "joe",
  "email": "joe@example.com"
}

Recipe B — transform an array: Connect the array to an array_map (map) block. It applies the connected function to every element and returns a new array with the results — the standard way to convert a function_search result into response objects. It accepts a concurrency number in-pin and exposes an error value out-pin; array_map_parse (map and parse) is the variant for parsing each element along the way.

Recipe C — denormalized writes: Because RUAL storage has no relationships, include all data you need inside each document. Build the fields with mutations_set_bp_field_multiple and write them with function_create_document or function_update_document. When a source document changes, keep the embedded copies in sync with a storage_event flow — see Data Modelling Without Relations.

4. Error Handling

Goal: Make failures visible, answer them properly, and retry work that deserves a second attempt.

When to use: Every flow that touches storage, HTTP requests, or any other operation that can fail. RUAL has no try/catch — blocks that can fail expose a success condition pin and an error value pin, and the flow keeps running unless you branch on them.

Recipe — log and reply (error_demo style):

A typical error payload looks like this:

{
  "success": false,
  "error": "Document not found for the given GUID"
}

Notes:

• Retry via the queue: for background work that may fail transiently, (re)schedule it with function_custom_execute_from_queue (execute in queue). It runs the function at a given time without waiting, and accepts an optional unique_id and debounce to avoid duplicate runs. See Queue.
• Audit failures yourself: the blueprint audit log records modifications, not runtime errors. For a failure trail, write errors to a dedicated storage with function_create_document or send them to an external webhook — the patterns from Error Handling.
• An unconnected error pin means failures pass silently — always wire it somewhere. See Reading error messages.

5. Caching Strategies

Goal: Stop paying for the same query twice.

When to use: Read-heavy flows and high-traffic pages — a single search is cheap, but 300 simultaneous page visits run it 300 times a minute.

Recipe A — built-in search cache: function_search has a Cache Key value in-pin. Pass a key that identifies the query (for example the searched user GUID) and repeated identical searches are served from cache instead of hitting storage again.

Recipe B — manual Redis check-aside:

Recipe C — invalidate on write: cached data must die when the underlying documents change. Add a storage_event (trigger event) flow on the storage — it fires on created, updated, removed, and saved events — and remove the affected keys with function_redis_cache_delete_key (delete), or overwrite them with fresh data right away.

Recipe D — precompiled static lookups: for values that never change, reuse one block for identical values across the blueprint instead of duplicating blocks — RUAL precompiles block outputs for efficiency and reuses them on every execution.

Notes:

• Never cache what must be real-time. If a screen must show the absolute latest data, prefer the disable cache query option over cached results — and read the trade-off in Common Pitfalls.
• Invalidate narrowly: delete or overwrite the keys affected by the write instead of flushing broad key ranges.
• Background on cache strategy lives in Caching with Redis and Common Pitfalls.

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem