Authentication Implementation Guide
Step 1: Obtain API Credentials
Before you can use the API Seal Metrics, you need to obtain your API credentials:
1. Contact your account manager or support team to request API access
2. You will receive your API credentials (email and password)
3. Store these credentials securely in your application environment
Step 2: Implement the Authentication Flow
```python
import requests
import json
import os
from datetime import datetime, timedelta
# Store credentials securely (e.g., in environment variables)
API_EMAIL = os.environ.get("SEAL_METRICS_EMAIL")
API_PASSWORD = os.environ.get("SEAL_METRICS_PASSWORD")
API_BASE_URL = "https://app.sealmetrics.com/api"
def get_auth_token():
"""
Authenticate with the API and return a valid token.
Handles token caching and renewal.
"""
# Check if we have a cached token
token_data = load_cached_token()
if token_data and is_token_valid(token_data):
return token_data["access_token"]
# If no valid token, request a new one
url = f"{API_BASE_URL}/auth/login"
payload = {
"email": API_EMAIL,
"password": API_PASSWORD
}
headers = {
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
token_data = response.json()
# Cache the token
save_token_to_cache(token_data)
return token_data["access_token"]
else:
raise Exception(f"Authentication failed: {response.text}")
def load_cached_token():
"""Load token from cache if available."""
try:
with open(".token_cache.json", "r") as f:
return json.load(f)
except (FileNotFoundError, json.JSONDecodeError):
return None
def save_token_to_cache(token_data):
"""Save token to cache for future use."""
with open(".token_cache.json", "w") as f:
json.dump(token_data, f)
def is_token_valid(token_data):
"""Check if the token is still valid."""
expires_at = datetime.fromisoformat(token_data["expires_at"].replace("Z", "+00:00"))
# Add a buffer of 5 minutes to ensure we renew before expiration
return datetime.now(expires_at.tzinfo) < (expires_at - timedelta(minutes=5))
def get_auth_headers():
"""Return headers with authentication token for API requests."""
token = get_auth_token()
return {
"Authorization": f"Bearer {token}",
"Accept": "application/json",
"Connection": "keep-alive",
"Accept-Encoding": "gzip, deflate, br"
}
```
Step 3: Use the Authentication in Your API Requests
```python
def make_api_request(endpoint, params=None):
"""Make an authenticated request to the API."""
headers = get_auth_headers()
url = f"{API_BASE_URL}/{endpoint}"
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
return response.json()
elif response.status_code == 401:
# Token might be expired, force refresh and try again
headers["Authorization"] = f"Bearer {get_auth_token(force_refresh=True)}"
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
return response.json()
# If we still have an error
raise Exception(f"API request failed: {response.text}")
```
Data Retrieval Implementation Guide
Step 1: Set Up Your Project
Create a new project and install the required dependencies:
```bash
# Create a new directory for your project
mkdir seal-metrics-integration
cd seal-metrics-integration
# Create a virtual environment (Python)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install required packages
pip install requests python-dotenv
```
Step 2: Create Environment Configuration
Create a `.env` file to store your credentials:
```
SEAL_METRICS_EMAIL=[email protected]
SEAL_METRICS_PASSWORD=your_password
SEAL_METRICS_ACCOUNT_ID=your_account_id
```
Step 3: Create a Base API Client
Create a file named `api_client.py` with a comprehensive client implementation (see the full implementation guide for details).
Step 4: Create Example Usage Scripts
Create a file named `examples.py` with example usage of the API client (see the full implementation guide for details).
Pagination Implementation Guide
When working with large datasets, you'll need to implement pagination to retrieve all records:
```python
def get_all_pages(client, endpoint, params):
"""
Retrieve all pages of data from a paginated endpoint.
Args:
client: SealMetricsClient instance
endpoint: API endpoint path
params: Base parameters for the request
Returns:
List of all data items across all pages
"""
all_data = []
page_size = params.get("limit", 100)
current_skip = params.get("skip", 0)
while True:
# Update skip parameter for current page
params["skip"] = current_skip
# Make the request
response = client.make_request(endpoint, params=params)
# Extract data
data = response.get("data", [])
# If no data or empty list, we've reached the end
if not data or len(data) == 0:
break
# Add this page's data to our results
all_data.extend(data)
# If we got fewer results than the page size, we've reached the end
if len(data) < page_size:
break
# Move to the next page
current_skip += page_size
return all_data
```
Error Handling Implementation Guide
Implement robust error handling to manage API request failures:
```python
def make_api_request_with_retry(client, endpoint, params=None, max_retries=3, retry_delay=2):
"""
Make an API request with automatic retries for transient errors.
Args:
client: SealMetricsClient instance
endpoint: API endpoint path
params: Request parameters
max_retries: Maximum number of retry attempts
retry_delay: Delay between retries in seconds
Returns:
API response data
"""
import time
retries = 0
last_exception = None
while retries <= max_retries:
try:
return client.make_request(endpoint, params=params)
except Exception as e:
last_exception = e
# Check if this is a retryable error
if "rate limit" in str(e).lower() or "timeout" in str(e).lower():
retries += 1
if retries <= max_retries:
# Wait before retrying, with exponential backoff
wait_time = retry_delay * (2 ** (retries - 1))
print(f"Retrying in {wait_time} seconds... (Attempt {retries}/{max_retries})")
time.sleep(wait_time)
continue
else:
# Non-retryable error
raise
# If we've exhausted all retries
raise Exception(f"Max retries exceeded. Last error: {last_exception}")
```