User Guide¶

This guide provides comprehensive information about using the Amorphic SDK effectively.

Getting Started with Wrapper Classes¶

The Amorphic SDK provides enhanced wrapper classes that simplify authentication, provide helper utilities, and offer a more user-friendly interface to the underlying OpenAPI client.

Overview of Wrapper Classes¶

AmorphicApiClient: Enhanced API client with built-in authentication, version checking, and logging
TokenFetcher: Utility for fetching PAT tokens from various sources (environment variables, AWS SSM, Secrets Manager)
HelpCommand: Comprehensive help system for discovering and exploring available APIs

Authentication Setup¶

The SDK supports multiple mechanisms for supplying the PAT token and connection parameters. All operational and automated workflows should source credentials from AWS SSM Parameter Store or AWS Secrets Manager. Direct environment variable injection inside application code is not supported as an operational pattern.

AWS SSM Parameter Store (Recommended)¶

Configuration values are stored in SSM and fetched at runtime:

import certifi
import boto3
from openapi_client.amorphic_api_client import AmorphicApiClient

ssm = boto3.client('ssm')
api_gw_url = ssm.get_parameter(Name='adp/amorphic/config/apigwurl', WithDecryption=False)['Parameter']['Value']  # String type; use WithDecryption=True for SecureString
role_id    = ssm.get_parameter(Name='adp/amorphic/config/roleid',   WithDecryption=False)['Parameter']['Value']  # String type; use WithDecryption=True for SecureString

client = AmorphicApiClient.create_with_auth(
    host=api_gw_url,
    role_id=role_id,
    ssl_ca_cert=certifi.where(),
    ssm_parameter='adp/amorphic/config/pattoken'
)

AWS Secrets Manager¶

Use when secrets policy requires Secrets Manager storage or rotation support. The secret value must be stored in plain text format.

client = AmorphicApiClient.create_with_auth(
    host=api_gw_url,
    role_id=role_id,
    ssl_ca_cert=certifi.where(),
    secret_arn='arn:aws:secretsmanager:<region>:<account>:secret:<secret-name>'
)

Environment Variable (Local Development Only)¶

For local development and quick testing, variables can be set at the OS level and read by the SDK. Variables must not be assigned inside application code.

# Set in the shell before running the script
export PAT_TOKEN="<personal-access-token>"
export API_GW_URL="<api-gateway-url>"
export ROLE_ID="<role-id>"

import os
import certifi
from openapi_client.amorphic_api_client import AmorphicApiClient

client = AmorphicApiClient.create_with_auth(
    host=os.environ['API_GW_URL'],
    role_id=os.environ['ROLE_ID'],
    ssl_ca_cert=certifi.where(),
    env_var='PAT_TOKEN'
)

For the complete parameter reference, see the AmorphicApiClient documentation.

Working with APIs¶

Using the Datasets API¶

from openapi_client.api.datasets_api import DatasetsApi
from openapi_client.models.dataset_metadata import DatasetMetadata

# Create API instance
datasets_api = DatasetsApi(client)

# List datasets
try:
    datasets = datasets_api.list_datasets(role_id=role_id)
    print(f"Found {len(datasets.datasets)} datasets")
except Exception as e:
    print(f"Failed to list datasets: {e}")
    raise

# Create a new dataset
dataset_metadata = DatasetMetadata(
    dataset_name="my_dataset",
    dataset_description="Dataset created via SDK",
    dataset_type="internal",
    domain="examples",
    keywords=["example", "test"],
    file_type="csv",
    table_update="append",
    data_classification=["INTERNAL"],
    file_delimiter=",",
    enable_data_validation=True,
    datasource_type="api",
    TargetLocation="lf"
)

try:
    result = datasets_api.create_dataset(
        role_id=role_id,
        dataset_metadata=dataset_metadata
    )
except Exception as e:
    print(f"Failed to create dataset: {e}")
    raise

Next Steps¶

Explore the Wrapper Classes for detailed wrapper class documentation
Check out Examples for practical examples using wrapper classes
Browse the API Reference for complete API reference
Discover available functionality using the built-in help system - see HelpCommand documentation