Developer Guide

Introduction

The Developer Guide provides comprehensive resources for integrating with the Trazadera Golden platform. Whether you're building data pipelines, integrating master data into applications, or automating deduplication workflows, this guide will help you get started quickly.

Target Audience: Software developers, integration engineers, and DevOps teams building solutions with Trazadera Golden.

Quick Start (5 Minutes)

Get up and running with the Golden API in minutes.

Prerequisites

API URL provided by your administrator (e.g., https://golden.yourcompany.com)
Access token with appropriate permissions
curl or any HTTP client

Step 1: Set Up Environment Variables

BASH

export GOLDEN_URL="https://golden.yourcompany.com"
export GOLDEN_TOKEN="golden:YourAccessTokenHere"

Step 2: Verify Connection

BASH

curl -X GET "${GOLDEN_URL}/api/security/whoami" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json"

Expected Response:

JSON

{
  "token": "golden:***",
  "id": "t-abc123",
  "role": "STEWARD",
  "name": "API Integration",
  "type": "ACCESS_TOKEN"
}

Step 3: List Available Entities

BASH

curl -X GET "${GOLDEN_URL}/api/entities" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json"

Step 4: Search for Records

BASH

curl -X POST "${GOLDEN_URL}/api/golden/search" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "customers",
    "query": "[email protected]",
    "limit": 10
  }'

Congratulations! You've made your first API calls to Golden.

Authentication

Golden uses Bearer token authentication for all API requests.

Token Types

Type	Use Case	Expiration
Access Token	API integrations, automation	Configurable (months/years)
JWT Token	User sessions, web applications	Short-lived (hours)

Using Access Tokens (Recommended for Integrations)

Access tokens are long-lived and ideal for server-to-server integrations.

BASH

# All requests require the Authorization header
curl -X GET "${GOLDEN_URL}/api/entities" \
  -H "Authorization: Bearer golden:YourAccessToken" \
  -H "Content-Type: application/json"

Important:

Access tokens always start with golden: prefix
Store tokens securely (environment variables, secret managers)
Never commit tokens to version control
Use the minimum required role (prefer STEWARD over ADMIN)

Using JWT Tokens (For Applications)

For user-facing applications, authenticate with credentials to get a JWT:

BASH

curl -X POST "${GOLDEN_URL}/api/security/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePassword123!"
  }'

Response:

JSON

{
  "token": "eyJhbGciOiJIUzUxMiJ9...",
  "type": "Bearer",
  "expiresIn": 3600000
}

For complete security documentation, see Security.

Core API Operations

Working with Entities

Entities are the foundation of master data management in Golden.

List all entities:

BASH

curl -X GET "${GOLDEN_URL}/api/entities" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Get entity details:

BASH

curl -X GET "${GOLDEN_URL}/api/entities/customers" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Get entity statistics:

BASH

curl -X GET "${GOLDEN_URL}/api/entities/customers/statistics" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Searching Records

Simple text search:

BASH

curl -X POST "${GOLDEN_URL}/api/golden/search" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "customers",
    "query": "john smith",
    "limit": 20
  }'

Search by specific field:

BASH

curl -X POST "${GOLDEN_URL}/api/golden/search" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "customers",
    "query": "email:[email protected]",
    "limit": 10
  }'

Response structure:

JSON

{
  "total": 3,
  "records": [
    {
      "id": "rec-001",
      "score": 0.95,
      "data": {
        "email": "[email protected]",
        "full_name": "John Smith",
        "phone": "+1-555-0100"
      }
    }
  ]
}

Managing Records

Get a single record:

BASH

curl -X GET "${GOLDEN_URL}/api/golden/record/rec-001?entity=customers" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Get expanded record with metadata:

BASH

curl -X GET "${GOLDEN_URL}/api/golden/record/rec-001?entity=customers&expanded=true" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Insert or update a record (upsert):

BASH

curl -X POST "${GOLDEN_URL}/api/golden/upsert" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "customers",
    "records": [
      {
        "id": "crm-12345",
        "email": "[email protected]",
        "full_name": "Jane Doe",
        "phone": "+1-555-0200",
        "source": "CRM"
      }
    ]
  }'

Delete a record:

BASH

curl -X DELETE "${GOLDEN_URL}/api/golden/record/rec-001?entity=customers" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Working with Buckets (Duplicates)

Buckets group potential duplicate records together.

List buckets needing review:

BASH

curl -X GET "${GOLDEN_URL}/api/golden/buckets?entity=customers&classification=REVIEW" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Get bucket details:

BASH

curl -X GET "${GOLDEN_URL}/api/golden/bucket/bucket-001?entity=customers" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Merge duplicate records:

BASH

curl -X PUT "${GOLDEN_URL}/api/golden/bucket/merge" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "customers",
    "bucketId": "bucket-001"
  }'

Split records (not duplicates):

BASH

curl -X PUT "${GOLDEN_URL}/api/golden/bucket/disconnect" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "customers",
    "bucketId": "bucket-001",
    "recordIds": ["rec-002", "rec-003"]
  }'

Working with Tables

Tables provide direct data access and bulk operations.

List tables:

BASH

curl -X GET "${GOLDEN_URL}/api/tables" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Query table records:

BASH

curl -X POST "${GOLDEN_URL}/api/tables/customers/query" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": "email LIKE '\''%@example.com'\''",
    "limit": 100,
    "offset": 0
  }'

Export table to file:

BASH

curl -X POST "${GOLDEN_URL}/api/tables/customers/export" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "CSV",
    "filter": "created_at > '\''2024-01-01'\''"
  }'

Managing Tasks

Long-running operations execute as background tasks.

List running tasks:

BASH

curl -X GET "${GOLDEN_URL}/api/tasks/instances?status=RUNNING" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Get task status:

BASH

curl -X GET "${GOLDEN_URL}/api/tasks/instances/task-001" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Cancel a task:

BASH

curl -X DELETE "${GOLDEN_URL}/api/tasks/instances/task-001" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Task Status Values:

Status	Description
`QUEUED`	Waiting to start
`RUNNING`	Currently executing
`COMPLETED`	Finished successfully
`FAILED`	Finished with error
`CANCELLED`	Cancelled by user

Error Handling

HTTP Status Codes

Code	Meaning	Action
`200`	Success	Parse JSON response
`400`	Bad Request	Check request parameters
`401`	Unauthorized	Check/refresh token
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource doesn't exist
`409`	Conflict	Invalid state transition
`500`	Server Error	Retry or contact support

Error Response Format

JSON

{
  "errors": [
    "Entity 'customers' not found"
  ]
}

Handling Errors in Code

PY

import requests

response = requests.get(
    f"{GOLDEN_URL}/api/entities/customers",
    headers={"Authorization": f"Bearer {GOLDEN_TOKEN}"}
)

if response.status_code == 200:
    entity = response.json()
elif response.status_code == 401:
    # Token expired or invalid - re-authenticate
    refresh_token()
elif response.status_code == 403:
    # Insufficient permissions
    raise PermissionError("Access denied")
elif response.status_code == 404:
    # Entity doesn't exist
    raise ValueError("Entity not found")
else:
    # Other error
    errors = response.json().get("errors", [])
    raise Exception(f"API error: {errors}")

Integration Patterns

Pattern 1: Real-Time Record Lookup

Use search to find matching records before creating duplicates in your system.

PY

def find_customer(email):
    response = requests.post(
        f"{GOLDEN_URL}/api/golden/search",
        headers={
            "Authorization": f"Bearer {GOLDEN_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "entity": "customers",
            "query": f"email:{email}",
            "limit": 1
        }
    )
    
    if response.status_code == 200:
        results = response.json()
        if results["total"] > 0:
            return results["records"][0]
    return None

Pattern 2: Batch Data Synchronization

Sync data periodically using upsert operations.

PY

def sync_customers(records):
    # Batch size for optimal performance
    BATCH_SIZE = 1000
    
    for i in range(0, len(records), BATCH_SIZE):
        batch = records[i:i + BATCH_SIZE]
        
        response = requests.post(
            f"{GOLDEN_URL}/api/golden/upsert",
            headers={
                "Authorization": f"Bearer {GOLDEN_TOKEN}",
                "Content-Type": "application/json"
            },
            json={
                "entity": "customers",
                "records": batch
            }
        )
        
        if response.status_code != 200:
            print(f"Error syncing batch {i}: {response.json()}")

Pattern 3: Webhook-Style Change Detection

Poll for changes since last sync using table queries.

PY

def get_changes_since(last_sync_time):
    response = requests.post(
        f"{GOLDEN_URL}/api/tables/customers/query",
        headers={
            "Authorization": f"Bearer {GOLDEN_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "filter": f"_updated > '{last_sync_time}'",
            "limit": 1000
        }
    )
    
    return response.json()["records"]

Pattern 4: Deduplication Pipeline Integration

Trigger reindexing after bulk data loads.

BASH

# 1. Load data via upsert
curl -X POST "${GOLDEN_URL}/api/golden/upsert" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @records.json

# 2. Trigger entity reindex
curl -X POST "${GOLDEN_URL}/api/entities/customers/index" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

# 3. Monitor task completion
curl -X GET "${GOLDEN_URL}/api/tasks/instances?status=RUNNING" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

SDK & Client Libraries

Java OpenAPI Client

The official Java client library provides type-safe API access.

Maven dependency:

XML

<dependency>
  <groupId>com.trazadera</groupId>
  <artifactId>trazadera-golden-openapi</artifactId>
  <version>16-SNAPSHOT</version>
</dependency>

Usage example:

JAVA

ApiClient client = new ApiClient();
client.setBasePath("https://golden.yourcompany.com");
client.setBearerToken("golden:YourAccessToken");

GoldenApi goldenApi = new GoldenApi(client);

// Search for records
SearchResponse response = goldenApi.search(
    new SearchRequest()
        .entity("customers")
        .query("[email protected]")
        .limit(10)
);

for (Record record : response.getRecords()) {
    System.out.println(record.getData());
}

See Golden OpenAPI Library for complete documentation.

Command Line Client (CLI)

The Golden CLI enables scripting and automation from the terminal.

Installation:

BASH

git clone https://github.com/trazadera-public/trazadera-golden-cli.git
cd trazadera-golden-cli
mvn clean package
export PATH=$PATH:$(pwd)/bin

Usage:

BASH

# Configure connection
golden config set url https://golden.yourcompany.com
golden config set token golden:YourAccessToken

# List entities
golden entity list

# Search records
golden golden search --entity customers --query "[email protected]"

# Export data
golden table export customers --format CSV --output customers.csv

See Golden Command Line Client for complete documentation.

API Reference

Interactive Documentation

Access the Swagger UI for interactive API exploration:

CODE

https://your-golden-server/swagger-ui.html

OpenAPI Specification

Download the OpenAPI definition for code generation:

BASH

curl -X GET "${GOLDEN_URL}/api/configuration/openapi" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
  -o golden-api.json

API Version

Check the current API version:

BASH

curl -X GET "${GOLDEN_URL}/api/configuration/version" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Developer Resources

Documentation

Golden API - Complete API overview
Golden API Documentation - OpenAPI reference
Security - Authentication and authorization

Tools & Libraries

Golden OpenAPI Library - Java client
Golden Command Line Client - CLI tool

Concepts

Entities - Understanding entities
Golden Records - How deduplication works
Resources - Data integration components
Tasks - Background processing

Examples

Example: Customer Data Integration - End-to-end walkthrough
Example: Manual Deduplication Workflow - Bucket operations

Getting Help

Swagger UI - Interactive API documentation at /swagger-ui.html
Health Check - System status at /actuator/health
Support - Contact your administrator or [email protected]