Golden API Documentation

Introduction

The Golden API is fully documented using the OpenAPI 3.0 specification. This page explains how to access, explore, and use the API documentation for integration and development.

Swagger UI (Interactive Documentation)

The easiest way to explore the Golden API is through the built-in Swagger UI interface.

Accessing Swagger UI

Open your browser and navigate to:

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

Features

• Interactive exploration - Browse all endpoints organized by module

• Try it out - Execute API calls directly from the browser

• Request/Response schemas - View detailed data structures

• Authentication - Test with your access token

Using Swagger UI

Step 1: Authorize

1. Click the Authorize button (lock icon)

2. Enter your token: golden:YourAccessToken

3. Click Authorize to apply

Step 2: Explore Endpoints

1. Expand a module (e.g., golden, entity, table)

2. Click on an endpoint to see details

3. View parameters, request body schema, and response formats

Step 3: Test API Calls

1. Click Try it out on any endpoint

2. Fill in required parameters

3. Click Execute

4. View the response, including status code and body

OpenAPI Specification

The OpenAPI specification is a machine-readable API definition that can be used for code generation, documentation, and testing.

Download OpenAPI JSON

From the API:

curl -X GET "https://your-golden-server/api/configuration/openapi" \
  -H "Authorization: Bearer golden:YourAccessToken" \
  -o golden-api.json

From GitHub:

The trazadera-golden-openapi repository contains the latest API specification.

OpenAPI Structure

{
  "openapi": "3.0.1",
  "info": {
    "title": "GOLDEN-API",
    "description": "Trazadera Golden API",
    "version": "2.0.38"
  },
  "servers": [
    {
      "url": "https://your-golden-server",
      "description": "Golden API Server"
    }
  ],
  "paths": {
    "/api/entities": { ... },
    "/api/golden/search": { ... },
    "/api/tables": { ... }
  },
  "components": {
    "schemas": { ... },
    "securitySchemes": { ... }
  }
}

Check API Version

Always verify you're using the correct API version:

curl -X GET "https://your-golden-server/api/configuration/version" \
  -H "Authorization: Bearer golden:YourAccessToken"

Response:

{
  "version": "2.0.38"
}

API Modules

The Golden API is organized into functional modules (OpenAPI tags):

Core Modules

System Modules

Common Endpoints Reference

Authentication

Golden Records

Entities

Tables

Tasks

Request & Response Formats

Request Headers

All API requests require:

Authorization: Bearer golden:YourAccessToken
Content-Type: application/json
Accept: application/json

Success Response

{
  "id": "customers",
  "description": "Customer entity",
  "status": "COMPLETED",
  "records": 15000,
  "buckets": 14500
}

Error Response

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

Pagination

For list endpoints, use pagination parameters:

GET /api/entities?offset=0&limit=20

Response includes pagination info:

{
  "total": 150,
  "offset": 0,
  "limit": 20,
  "items": [ ... ]
}

Code Generation

Use the OpenAPI specification to generate client libraries for any language.

Using OpenAPI Generator

Install OpenAPI Generator:

npm install @openapitools/openapi-generator-cli -g

Generate Python client:

openapi-generator-cli generate \
  -i golden-api.json \
  -g python \
  -o ./golden-python-client

Generate TypeScript client:

openapi-generator-cli generate \
  -i golden-api.json \
  -g typescript-fetch \
  -o ./golden-ts-client

Generate Java client:

openapi-generator-cli generate \
  -i golden-api.json \
  -g java \
  -o ./golden-java-client

Pre-built Libraries

We provide official client libraries:

• Java: Golden OpenAPI Library

• CLI: Golden Command Line Client

Testing the API

Using curl

# Set environment variables
export GOLDEN_URL="https://your-golden-server"
export GOLDEN_TOKEN="golden:YourAccessToken"

# Test authentication
curl -X GET "${GOLDEN_URL}/api/security/whoami" \
  -H "Authorization: Bearer ${GOLDEN_TOKEN}"

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

# Search records
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}'

Using HTTPie

# Authentication
http GET ${GOLDEN_URL}/api/security/whoami \
  Authorization:"Bearer ${GOLDEN_TOKEN}"

# Search records
http POST ${GOLDEN_URL}/api/golden/search \
  Authorization:"Bearer ${GOLDEN_TOKEN}" \
  entity=customers [email protected] limit:=10

Using Postman

1. Import the OpenAPI specification (golden-api.json)

2. Set up environment variables (GOLDEN_URL, GOLDEN_TOKEN)

3. Configure Authorization header in collection settings

4. Explore and test endpoints

Troubleshooting

Swagger UI Not Loading

• Verify the server is running

• Check CORS settings if accessing from different domain

• Try clearing browser cache

"Unauthorized" in Swagger UI

• Click Authorize and enter your token

• Ensure token format is correct: golden:xxxxx

• Verify token hasn't expired

OpenAPI Download Fails

• Check authentication token is valid

• Verify you have permission to access configuration endpoints

• Try accessing /api/configuration/version first

Additional Resources

• Golden API - API overview and concepts

• Security - Authentication details

• Developer Guide - Complete developer documentation

• OpenAPI Specification - Official OpenAPI documentation