On this page
Implement Golden integration patterns
Apply verified Trazadera Golden API patterns for record lookup, controlled writes, bulk flows, and mastered-data delivery.
Choose an integration shape based on latency, volume, and who owns recovery. Golden supports synchronous record search and single-record writes alongside resource-driven table and entity operations.
Architects comparing web, synchronous, batch, delivery, and hybrid designs should first use Choose an enterprise integration approach.
Use this page to choose behavior and recovery strategy. Use the Golden API reference for exact record operations, the Table API for bulk work, and the schema catalog for request and response models.
Choose a pattern
| Need | Pattern | Important constraint |
|---|---|---|
| Check for an existing subject during a transaction | Record-shaped search | Adds a synchronous dependency |
| Create or correct one entity record | Single-record upsert | Requires STEWARD or ADMIN |
| Process an extract or large record set | Configured table load and entity synchronization | Follow the returned task |
| Deliver mastered records downstream | Configured destination | Design the receiver for safe redelivery |
Search before creating a source record
The search body is a record fragment shaped by the entity’s dataset. It is not a free-text query language.
import os
import requests
url = os.environ["GOLDEN_URL"]
token = os.environ["GOLDEN_TOKEN"]
response = requests.post(
f"{url}/api/golden/sample-customer-entity/search",
headers={"Authorization": f"Bearer {token}"},
json={
"record": {"email": "ana.garcia@example.com"},
"options": {},
"pageNumber": 0,
"pageSize": 10,
},
timeout=5,
)
response.raise_for_status()
matches = response.json()["result"]
An empty result means the submitted criteria found no matching record. It
does not prove the subject is absent under every possible criterion. Decide
explicitly whether your caller fails open, fails closed, or asks for review when
Golden is unavailable.
Upsert one record
POST /api/golden/{entity}/upsert accepts one record per request. It does not
accept a records batch.
Golden resolves the record a write addresses from its _id and the dataset
identity, computed after the entity’s pipeline. The rules, the conflict body
and what an update changes are in the record write reference.
Use the complete read–correct–verify–restore example
for Aurelia. It reads CRM-0001, keeps its business fields and _id, and sends
update:true.
Choose the write mode from what a wrong outcome would cost:
| Mode | Use when |
|---|---|
| No flag | The key decides: Golden updates the record it names, or creates one. On a DEFAULT dataset a free usable _id creates under that identifier |
update: true | Creating a second record would be less safe than failing the request |
insert: true | The record must be new; Golden refuses the request when the key already names one |
Treat a 409 or 410 as a data-state decision, not a generic retry signal:
the conflict body says whether to continue with a survivor, a restored record
or an existing record. Keep the source identity stable. A computed identity
that is missing or disagrees with a supplied _id is refused rather than
silently replaced.
Use this endpoint for controlled individual writes. For volume, configure a source, transformation or pipeline as needed, and load it through the entity’s synchronization.
Follow indexing after a write
When an entity indexes writes asynchronously, query:
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer ${GOLDEN_TOKEN}" \
"${GOLDEN_URL}/api/golden/sample-customer-entity/records/${RECORD_ID}/index-status"
The response reports PENDING, INDEXED, or FAILED, together with the time
first queued, last status change, attempt count, and an error when indexing
failed. Wait for INDEXED before diagnosing a newly written record as missing
from search.
An ADMIN can list failed entries and retry one or all of them through the
entity indexing-failure operations.
Run bulk work through configured resources
Bulk ingestion and export use saved resources and create asynchronous work. Validate the resources with representative data, start the appropriate table or entity operation, and follow its returned task identifier.
configured source → entity synchronization → searchable or resolved records
configured source → table load → a table that belongs to no entity
entity → configured destination → downstream system
An entity’s data is written through the entity: a table load into an entity’s table is refused. A synchronization applies the upsert’s identity rules and counts the rows it cannot key instead of stopping; see Entity synchronization.
Do not implement bulk upsert by assuming the single-record endpoint accepts an array. The exact load and synchronization request schemas are available in the running explorer where the deployment enables it.
Deliver mastered data
Use a supported Kafka, HTTP, JDBC, or Golden-table destination for managed delivery. A timeout can leave the sender uncertain whether a write was applied, so downstream consumers should use stable record identity and tolerate a safe repeat where their protocol allows it. A receiver must also implement the clear event that empties its mirror; the product event reference describes every payload a destination receives.
Golden does not document a generic table-query language or change-feed endpoint. Do not use undocumented SQL-like filters for polling. Use the supported table record filters from Query table data through the API or a configured destination.
Handle failures
| Status | Recommended response |
|---|---|
400 | Correct the request or data; do not retry unchanged |
401 | Obtain or replace the credential, then retry once |
403 | Stop; assign an appropriate role or change the workflow |
404 | Recheck the environment, path, and identifier |
409 | Read the conflict response and reconcile record state |
410 | Treat the addressed record as no longer available |
423 | Inspect whether the entity or resource is disabled or locked before retrying |
5xx | Retry only according to the operation’s write safety and your recovery policy |