Golden API

Trazadera Golden provides a full API based on REST and OpenAPI definition.

The Golden API has predictable resource-oriented URLs, accepts URL parameters, request parameters and request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Quick Reference

Item	Value
Base URL	`https://<your-instance>.trazadera.net/api`
Authentication	Bearer token in `Authorization` header
Content Type	`application/json`
API Specification	OpenAPI 3.0
Documentation	`/swagger-ui.html`

Getting Started

You need the API <GOLDEN_URL> and the access <GOLDEN_TOKEN> to start using the Golden API. Your administrator or Trazadera Support will provide you with this information.

Environment Setup

Set up your environment variables (replace with your actual values):

BASH

export GOLDEN_URL="https://your-instance.trazadera.net"
export GOLDEN_TOKEN="golden:YourAccessTokenHere"

Verify Connection

Test your connection with the /api/security/whoami endpoint:

BASH

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

Successful response (authenticated):

JSON

{
  "token": "golden:***",
  "id": "t-abc123",
  "role": "STEWARD",
  "permissions": {
    "entity.view": "ALLOW",
    "golden.search": "ALLOW",
    "golden.upsertRecord": "ALLOW"
  },
  "name": "My API Token",
  "type": "ACCESS_TOKEN"
}

Unauthenticated response:

JSON

{
  "type": "NONE"
}

Authentication

The Golden API uses access tokens to authenticate requests. Your Golden administrator can manage API keys, including creation, renewal, and deletion.

Authentication Rules

Requirement	Description
Header	`Authorization: Bearer <token>`
Token Format	Must have `golden:` prefix
Protocol	HTTPS required (HTTP calls will fail)
Scope	Token must be included in every request

Token Types

Type	Description	Use Case
Access Token	Long-lived API key	Service integrations, automation
JWT Token	Short-lived session token	Web UI, interactive applications

Example Request with Authentication

BASH

curl -X 'GET' "${GOLDEN_URL}/api/entity" \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Security Best Practice: Keep your API keys secure. They carry privileges based on their associated role.

Request Format

HTTP Methods

Method	Purpose	Example
`GET`	Retrieve resources	Get entity list
`POST`	Create resources or execute actions	Create entity, search records
`PUT`	Update resources	Update entity configuration
`DELETE`	Remove resources	Delete entity

Common Headers

BASH

# Required headers
-H "Authorization: Bearer ${GOLDEN_TOKEN}"
-H "Accept: application/json"

# For POST/PUT requests with body
-H "Content-Type: application/json"

URL Parameters

Many endpoints support query parameters for filtering and pagination:

BASH

# Pagination
curl "${GOLDEN_URL}/api/entity?page=0&size=20"

# Filtering
curl "${GOLDEN_URL}/api/entity?status=COMPLETED"

# Sorting
curl "${GOLDEN_URL}/api/entity?sort=created,desc"

Request Body

POST and PUT requests typically require a JSON body:

BASH

curl -X 'POST' "${GOLDEN_URL}/api/entity" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "my-entity",
      "description": "Customer deduplication entity"
    }'

Response Format

Success Responses

All successful responses return JSON with status code 200:

JSON

{
  "content": [...],
  "page": {
    "size": 20,
    "number": 0,
    "totalElements": 150,
    "totalPages": 8
  }
}

Paginated Results

List endpoints return paginated results:

Field	Description
`content`	Array of results
`page.size`	Items per page
`page.number`	Current page (0-based)
`page.totalElements`	Total items available
`page.totalPages`	Total pages available

HTTP Status Codes

Code	Result	Meaning
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid parameters or malformed request
`401`	Unauthorized	Missing or invalid authentication token
`403`	Forbidden	Insufficient permissions for this operation
`404`	Not Found	Resource does not exist
`409`	Conflict	Resource state conflict (e.g., entity already running)
`500`	Server Error	Unexpected system error

Error Response Format

JSON

{
  "errors": ["Detailed error message here"]
}

Example Error Handling

BASH

# Invalid endpoint
curl -X 'GET' "${GOLDEN_URL}/api/invalid" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"

# Response (404):
{"errors":["No static resource api/invalid."]}

API Modules

The Golden API is organized into modules (OpenAPI tags) that group related functionality.

Core Modules

Module	Description	Key Operations
golden	Golden Record management	Search, upsert, merge records
entity	Entity lifecycle management	Create, run, monitor entities
resource	Resource configuration	Datasets, indexers, classifiers
table	Table operations	CRUD, query, import/export
metric	Metrics and statistics	Quality metrics, dashboards

System Modules

Module	Description	Key Operations
security	Authentication & authorization	Users, tokens, roles
task	Task scheduling & monitoring	Schedule, cancel, status
event	Event logging	View system events
file	File management	Upload, download files
configuration	System configuration	Version, settings, OpenAPI

Common API Operations

Entity Operations

BASH

# List all entities
curl -X 'GET' "${GOLDEN_URL}/api/entity" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"

# Get specific entity
curl -X 'GET' "${GOLDEN_URL}/api/entity/my-entity" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"

# Run entity
curl -X 'POST' "${GOLDEN_URL}/api/entity/my-entity/run" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"

# Check entity status
curl -X 'GET' "${GOLDEN_URL}/api/entity/my-entity/status" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Golden Record Operations

BASH

# Search records
curl -X 'POST' "${GOLDEN_URL}/api/golden/my-entity/search" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "[email protected]",
      "page": 0,
      "size": 10
    }'

# Upsert record
curl -X 'POST' "${GOLDEN_URL}/api/golden/my-entity/upsert" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "source": "CRM",
      "sourceId": "12345",
      "data": {
        "name": "John Doe",
        "email": "[email protected]"
      }
    }'

# Get bucket details
curl -X 'GET' "${GOLDEN_URL}/api/golden/my-entity/bucket/B-12345" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}"

Table Operations

BASH

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

# Query table
curl -X 'POST' "${GOLDEN_URL}/api/table/customers/query" \
    -H "Authorization: Bearer ${GOLDEN_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "filter": "status = '\''active'\''",
      "page": 0,
      "size": 100
    }'

Retrieving API Version and OpenAPI Definition

Get API Version

BASH

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

# Response:
{"version":"2.0.38"}

Download OpenAPI Specification

BASH

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

The OpenAPI definition follows the OpenAPI 3.0 Specification.

OpenAPI Resources

Resource	Description
GitHub	trazadera-golden-openapi - API definition and Java client
Swagger UI	`<GOLDEN_URL>/swagger-ui.html` - Interactive API documentation
Live Spec	`<GOLDEN_URL>/api/configuration/openapi` - Current production API spec

Tip: Always use the OpenAPI version that matches your production environment.

Roles and Authorization

Your token is associated with a role that determines your permissions. See the Security section for details.

Role Hierarchy

Role	Capabilities
USER	Read-only access to data
STEWARD	Read and write access to data
ADMIN	Full access including configuration

Authorization Errors

BASH

# Response when lacking permissions (403):
{
  "errors": ["Access denied: insufficient permissions for operation 'entity.delete'"]
}

Security Best Practices

Practice	Description
Least Privilege	Grant only the minimum required permissions
Avoid ADMIN tokens	Use STEWARD or USER roles for integrations
Rotate tokens	Periodically regenerate API tokens
Secure storage	Never commit tokens to version control
HTTPS only	All API calls must use HTTPS

Rate Limiting and Performance

Best Practices

Practice	Recommendation
Batch operations	Use bulk endpoints when available
Pagination	Always paginate large result sets
Caching	Cache frequently accessed data client-side
Connection pooling	Reuse HTTP connections

Pagination Example

BASH

# First page
curl "${GOLDEN_URL}/api/entity?page=0&size=50"

# Next page
curl "${GOLDEN_URL}/api/entity?page=1&size=50"

Next Steps

Resource	Description
Golden API Documentation	Swagger UI and OpenAPI details
Golden OpenAPI Library	Java client library
Golden Command Line Client	CLI tool for automation
Developer Guide	Complete developer documentation