macOS-dev-setup-2

# NEXT STEPS

> **Directory Structure:** All project work should be organized under `~/Code/Projects/` to maintain clean separation from MacOS home directory. Tool configurations and cache files are already redirected to `~/Code/.dev/` via symlinks.

## REST API Work Tooling

Our environment already includes essential HTTP tools (`httpie`, `fx`, `jq`) from the main setup. For Marvel API development and JSONL embeddings pipeline work, add these specialized tools:

**API Development & Testing:**

Homebrew automatically handles installation paths - `brew install` puts CLI tools in `/opt/homebrew/bin` (already in MacOS user PATH), while `brew install --cask` installs GUI applications to `/Applications` for easy access.

```sh
# Postman alternative for API testing (GUI app)
# Insomnia: Modern REST client with workspaces, environment variables, and GraphQL support
brew install --cask insomnia

# Advanced HTTP client with collections (GUI app)  
# Bruno: Open-source API client focused on privacy and local file storage
brew install --cask bruno

# Additional JSON/HTTP utilities
# xh: Modern replacement for httpie with improved performance and JSON handling
brew install xh

# RestFox: Cross-platform REST client with offline-first approach (GUI app)
brew install --cask restfox
```

**What these tools provide:**

- **Insomnia**: Visual interface for API testing, similar to Postman but lighter
- **Bruno**: Local-first API client that stores collections as files (Git-friendly)  
- **xh**: Faster, more intuitive CLI alternative to curl/httpie for HTTP requests
- **RestFox**: Cross-platform GUI REST client with offline-first approach and request collections

**Marvel API Setup:**

Create environment variables for Marvel API credentials. Use direnv for project-specific settings to avoid cluttering global shell config, but in our case we're using this API in multiple places so we'll be editing our `.zshrc` to allow our local admin user access to our Marvel API keys. We'll then allow public facing hooks into these files when running locally, to keep our credentials private:

## Marvel Account Setup and API Keys

- Sign up for Marvel API account using existing Disney Plus / Marvel Unlimited account credentials

- Generated API keys from <https://developer.marvel.com/account>

- "tell us about your projects, 'I organize community upskilling events and I'll be utilizing the marvel api to teach Restful API concepts as well as how to transform the data for formatting in vector storage appropriate for GenAI (with a focus on Ultron as the community loves evil ai). The hope is this excites a new generation of developers while engaging them in the latest pipelines of gaining new insights out of available resources. I'll blog about my experiments at <https://builder.aws.com/community/@bryanchasko>

- Store in key manager or use a private repository, i.e., (`Marvel-API-Private`) for secure credential storage, i.e., Marvel-API-Private

```env
# Marvel API Keys
# Generated from: https://developer.marvel.com/account
# 
# SECURITY NOTE: This file contains sensitive API credentials
# - Keep this file private and never commit to public repositories
# - Ensure proper file permissions (600 - owner read/write only)

# Our Marvel API public key
MARVEL_PUBLIC_KEY="<publickey>"

# Our Marvel API private key  
MARVEL_PRIVATE_KEY="<privatekey>"

# Marvel API base URL
MARVEL_API_BASE_URL="https://gateway.marvel.com/v1/public"

# Optional: Rate limiting settings
MARVEL_API_RATE_LIMIT="3000"  # requests per day
```

- Configured environment variables for use across multiple projects as above

**Implementation Details:**

- **Approach**: multi-project accessibility
- **Storage**: Keys stored in this private repository with 600 file permissions
- **Shell Integration**: `.zshrc` configured to source these variables automatically on local MacOS
- **Projects**: Available to ultron-embeddings and future Marvel API projects

**Security Measures:**

- File contains sensitive API credentials
- Repository kept private and never committed to public platforms
- File permissions set to 600 (owner read/write only)
- Environment variables loaded globally via `.zshrc` sourcing

> **API Credentials:** Authorized users should reference actual API keys from `~/Code/Projects/Marvel-API-Private/secrets/marvel-api.env`

**Quick Marvel API Test (using httpie):**

The Marvel API uses a specific authentication scheme that requires:

Three parameters:

ts - A timestamp (current Unix time)
apikey - Your public API key
hash - An MD5 hash of: timestamp + private key + public key

The hash generation process:

All requests must include ts, apikey, and hash as query parameters
The API validates by recreating the hash server-side

We have have httpie installed. Now let's test the Marvel API connection with htppie.
HTTPie makes it easy to:

Send HTTP requests from the terminal with readable syntax (http GET ...)
Pass query parameters directly (characters==1009685 limit==1 ...)
Handle errors with --check-status (exits nonzero if the request fails)
Pipe the JSON output to jq for clean filtering

```sh
# Load environment variables (silent)
source ~/Code/Projects/Marvel-API-Private/secrets/marvel-api.env

# Quick checksum verification (safe for recording)
echo "API keys loaded and verified ✓"

# Generate timestamp and hash 
ts=$(date +%s)
hash=$(echo -n "${ts}${MARVEL_PRIVATE_KEY}${MARVEL_PUBLIC_KEY}" | md5sum | cut -d' ' -f1)

echo "Testing Marvel API for Ultron (limited to 1 result)..."

# Test with limit=1 to get just one result
http GET "https://gateway.marvel.com/v1/public/characters" \
  name=="Ultron" \
  limit==1 \
  ts==$ts \
  apikey==$MARVEL_PUBLIC_KEY \
  hash==$hash

# Full Test Example & Return
ultron-embeddings  main + 13:28 
❯ source ~/Code/Projects/Marvel-API-Private/secrets/marvel-api.env && ts=$(date +%s) && hash=$(echo -n "${ts}${MARVEL_PRIVATE_KEY}${MARVEL_PUBLIC_KEY}" | md5sum | cut -d' ' -f1) && http --check-status GET "https://gateway.marvel.com/v1/public/comics" characters==1009685 limit==1 orderBy=="-modified" ts==$ts apikey==$MARVEL_PUBLIC_KEY hash==$hash | jq '.data.results[0] | {title, description, price: (.prices[0].price // "N/A"), pageCount} // "No comic found."' && echo "Data provided by Marvel. © 2025 MARVEL"
{
  "title": "West Coast Avengers (2024) #10",
  "description": "THE MARK OF ULTRON! OMEGA ULTRON and his followers take on the West Coast Avengers for a final showdown! But as the West Coast Ultron's life hangs in the balance, can the team pull together to save him? And what will it cost Tony Stark if they succeed?",
  "price": 3.99,
  "pageCount": 32
}
Data provided by Marvel. © 2025 MARVEL
```

## EOF