orcatech-client 0.1.22

A Python API client for ORCATECH

ORCATECH Python API Client

A Python-based API client for interacting with the ORCATECH server API.

Overview

This library provides a programmatic interface to make HTTP requests to the ORCATECH API using specific endpoints and request methods. It includes support for authentication, data retrieval, and AWS integration capabilities.

Installation

pip install orcatech_client

Or install from source:

git clone <repository-url>
cd python
pip install -e .

Features

• API Client: Full-featured HTTP client for ORCATECH API endpoints
• Authentication: Bearer token authentication support
• Type Safety: Comprehensive schema types for observations, records, and data structures
• AWS Integration: Certificate management for AWS services
• Configuration: Environment-based configuration using .env files

Examples

Example 1: Get Study Homes (Helper Function)

The get_study_homes helper function retrieves all homes for a study with their sensors and hubs in a denormalized format:

from orcatech_client import APIClient, get_study_homes
from orcatech_client.http_client import HTTPClient

# Create client
client = APIClient(base_url="https://api.example.com")
client.headers["Authorization"] = "Bearer your-token"

# For self-signed certificates (testing only)
HTTPClient.verify_ssl = False

# Get all homes with their sensors and hubs
homes = get_study_homes(client, "https://api.example.com", study_id=6)

# Iterate through results
for home in homes:
    print(f"Home: {home.name} (ID: {home.id})")
    print(f"  Hubs: {len(home.hubs)}")
    print(f"  Sensors: {len(home.sensors)}")

    for hub in home.hubs:
        print(f"    Hub: {hub.name}")
        print(f"      Model: {hub.model.name} (Vendor: {hub.model.vendor.name})")
        print(f"      Serial: {hub.serial_number}")
        print(f"      MAC: {hub.mac_address}")

    for sensor in home.sensors:
        print(f"    Sensor: {sensor.name}")
        print(f"      Model: {sensor.model.name}")
        if sensor.area and sensor.area.name:
            print(f"      Area: {sensor.area.name}")

Example 2: Basic API Client Usage

from orcatech_client.client import APIClient
from orcatech_client.config import Config, Scope

# Initialize configuration
Config.validate()
host = Config.HOST_URL
token = Config.AUTH_TOKEN

# Create client
client = APIClient(host)
client.headers["Authorization"] = f"Bearer {token}"

# Make API requests
scope = Scope["STUDY"]
scope_id = 2
data_schema = "com.orcatech.measure.access.period"
observation_uuid = "your-observation-uuid"

result = client.get_observation(
    host,
    scope,
    scope_id,
    data_schema,
    observation_uuid
)

Example 3: AWS Certificate Management

from orcatech_client.aws.aws_cert_manager import AWSCredentialManager

# Configuration
HOST = "https://test.c4.orcatech.org:8080/api/public"
SCOPE = "study"
SCOPE_ID = "1"
ITEM_ID = 1
SCHEMA = "com.orcatech.inventory.item"
AUTH_TOKEN = "your-auth-token"

# Read certificate and key files
with open("aws_cert.pem", "r") as cert_file:
    cert_pem = cert_file.read()

with open("aws_key.pem", "r") as key_file:
    key_pem = key_file.read()

# Combine certificate and key
combined_pem = cert_pem.strip() + "\n" + key_pem.strip()

# Initialize manager
manager = AWSCredentialManager(
    host=HOST,
    scope=SCOPE,
    scope_id=SCOPE_ID,
    auth_token=AUTH_TOKEN,
    schema=SCHEMA,
    demo_mode=False,
    insecure_ssl=True  # Set to False in production
)

# Create new AWS credentials
manager.create_aws_credentials(item_id=ITEM_ID, combined_pem=combined_pem)

# Or update existing credentials
manager.update_aws_credentials(item_id=ITEM_ID, combined_pem=combined_pem)

Configuration

Create a .env file in your project root:

HOST_URL=https://your-api-host.com
AUTH_TOKEN=your-bearer-token

Certificate File Format

AWS certificates should be in PEM format:

• aws_cert.pem - The device certificate
• aws_key.pem - The private key

Important: Never commit .pem files to version control. They are automatically ignored by .gitignore.

Available Methods

Core HTTP Methods

• get() - Generic GET requests
• post() - Generic POST requests
• put() - Generic PUT requests
• delete() - Generic DELETE requests
• authenticate() - Handle authentication

Records

• get_record() - Get an individual record
• get_records() - Get a list of records
• get_all_records() - Get all records matching query params
• get_private_records() - Get a list of private records

Observations

• get_observation() - Get a specific observation
• get_observations() - Get a list of observations
• get_record_observations() - Get observations related to a record

Graph/Relationships

• get_Record_Nodes() - Get related records as graph nodes
• get_Record_Edges() - Get relationships as graph edges

Scopes & Plugins

• get_scope() - Get a scope record
• get_scopes() - Get a subset of scope records
• get_available_plugins() - Get available plugins for a scope

Other

• get_record_field_resource() - Get large text resource for a record field
• get_external() - Get external records using integrations
• get_migration_status() - Get platform migration status
• get_nonce() - Retrieve a nonce value
• get_SAML2_certificate() - Get public SAML2 certificate
• get_history() - Get historical records
• get_schema_field_history() - Get historical field records
• get_record_field_history() - Get historical field values for a record

Helper Functions

• get_study_homes() - Get denormalized list of homes with sensors and hubs

Requirements

• Python >= 3.6
• requests
• python-dotenv

Author

Kezman Saboi

License

MIT License