orcatech-client 0.1.22
A Python API client for ORCATECH
Requires Python: >=3.6

# 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

```bash
pip install orcatech_client
```

Or install from source:

```bash
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:

```python
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

```python
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

```python
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