|
| 1 | +# QuickStarts API Toolkit |
| 2 | +Experiment with Sigma API calls and learn common request flows |
| 3 | + |
| 4 | +## Features |
| 5 | + |
| 6 | +### Recipes: |
| 7 | +- **Smart Parameter Detection**: Automatically detects and provides dropdown selection for Sigma resources (teams, members, workbooks, etc.) |
| 8 | +- **Interactive Execution**: Run recipes directly in the browser with real-time results |
| 9 | +- **Parameter Summary**: View which parameters were used in each request |
| 10 | +- **Code Viewing**: Browse the actual JavaScript code for each recipe |
| 11 | + |
| 12 | +### Quick API Explorer: |
| 13 | +- **Common Endpoints**: Curated list of the most useful Sigma API endpoints |
| 14 | +- **Zero Setup**: List endpoints require no parameters - perfect for quick exploration |
| 15 | +- **One Parameter**: Detail endpoints need just one ID to get specific resource information |
| 16 | +- **Alphabetical Organization**: Easy to find the endpoint you need |
| 17 | + |
| 18 | +## Authentication & Config Management |
| 19 | + |
| 20 | +### Smart Config System: |
| 21 | +- **Complete Configuration Storage**: Server endpoints + API credentials stored together as named "configs" |
| 22 | +- **Multi-Environment Support**: Easily switch between Production, Staging, Development environments |
| 23 | +- **One-Click Environment Switching**: Load complete configurations instantly |
| 24 | +- **Encrypted Local Storage**: AES-256 encryption for credential security |
| 25 | + |
| 26 | +### Config Management Features: |
| 27 | +- **Quick Start**: Load saved configs with one click - no manual entry needed |
| 28 | +- **Create New Configs**: Mix and match server endpoints with credentials |
| 29 | +- **Update Existing Configs**: Modify and save changes to existing configurations |
| 30 | +- **Delete Configs**: Remove configs you no longer need |
| 31 | +- **Auto-Save**: Configs saved automatically during authentication when enabled |
| 32 | +- **Manual Save**: Explicit save button for immediate config storage |
| 33 | + |
| 34 | +### Token Management: |
| 35 | +- **File-Based Storage**: Authentication tokens cached in system temp directory |
| 36 | +- **Persistent Sessions**: Tokens survive browser/server restarts for the full hour |
| 37 | +- **Automatic Expiration**: Tokens expire after 1 hour (Sigma's standard lifetime) |
| 38 | +- **Auto-Cleanup**: Expired tokens automatically detected and removed |
| 39 | +- **Manual Session End**: Clear authentication anytime with 🚪 End Session button |
| 40 | + |
| 41 | +### Storage Locations |
| 42 | + |
| 43 | +**Config Storage (encrypted)**: |
| 44 | +- **macOS**: `~/Library/Application Support/.sigma-portal/encrypted-keys.json` |
| 45 | +- **Windows**: `%APPDATA%\.sigma-portal\encrypted-keys.json` |
| 46 | +- **Linux**: `~/.config/.sigma-portal/encrypted-keys.json` |
| 47 | + |
| 48 | +**Token Cache (temporary)**: |
| 49 | +- **macOS**: `/var/folders/.../sigma-portal-token.json` |
| 50 | +- **Windows**: `%TEMP%\sigma-portal-token.json` |
| 51 | +- **Linux**: `/tmp/sigma-portal-token.json` |
| 52 | + |
| 53 | +### Developer Experience Benefits |
| 54 | +- **Environment Switching**: Instant switch between Production ↔ Staging ↔ Development |
| 55 | +- **Zero Re-entry**: Load complete configs without typing credentials repeatedly |
| 56 | +- **Secure Storage**: Military-grade AES-256 encryption for stored credentials |
| 57 | +- **Clean Separation**: Configs stored outside project directory (never committed to git) |
| 58 | +- **Visual Feedback**: Clear indicators show saved/unsaved state and notifications |
| 59 | +- **Flexible Workflow**: Session-only credentials OR persistent named configs |
| 60 | + |
| 61 | +### Config Workflow |
| 62 | +1. **First Time**: Enter server endpoint + credentials → Save as named config (e.g., "Production") |
| 63 | +2. **Daily Use**: Quick Start → Select "Production" → Instantly loaded and ready |
| 64 | +3. **Environment Switch**: Quick Start → Select "Staging" → Switched in one click |
| 65 | +4. **New Environment**: "✨ New Config" → Enter details → Save with new name |
| 66 | + |
| 67 | +## Getting Started |
| 68 | +Sigma_QuickStart_Public_Repo |
| 69 | + |
| 70 | + |
| 71 | +1. **Setup**: `npm install && npm run dev` |
| 72 | +2. **First-Time Config**: Open any recipe → **Config** tab → Enter server endpoint + credentials → Save as named config |
| 73 | +3. **Daily Use**: **Quick Start** section → Select your saved config → Ready to go! |
| 74 | +4. **Explore**: Use the ⚡ Quick API tab to explore common endpoints with smart parameters |
| 75 | +5. **Run Recipes**: Browse recipes by category and execute them with real-time results |
| 76 | + |
| 77 | +### Config Tab Features |
| 78 | +- **Quick Start**: Load saved configs instantly (appears when configs exist) |
| 79 | +- **Server Endpoint**: Choose your Sigma organization's server location |
| 80 | +- **API Credentials**: Enter Client ID and Client Secret |
| 81 | +- **Config Storage**: Save complete configurations with names like "Production", "Staging" |
| 82 | +- **Save Config**: Manual save button for immediate storage |
| 83 | +- **New Config**: Clear form to create fresh configurations |
| 84 | +- **Delete**: Remove configs you no longer need (🗑️ button when config selected) |
| 85 | + |
| 86 | +## Requirements |
| 87 | +- Node.js 18+ |
| 88 | +- Sigma API credentials (Client ID and Secret) |
| 89 | +- Valid Sigma organization access |
| 90 | + |
| 91 | +## Development |
| 92 | +```bash |
| 93 | +npm install |
| 94 | +npm run dev |
| 95 | +``` |
| 96 | + |
| 97 | +Navigate to `http://localhost:3001` to start exploring the Sigma API. |
| 98 | + |
| 99 | +## Project Structure |
| 100 | +``` |
| 101 | +recipe-portal/ |
| 102 | +├── app/ # Next.js app directory |
| 103 | +│ ├── api/ # API routes |
| 104 | +│ │ ├── execute/ # Recipe execution |
| 105 | +│ │ ├── resources/ # Resource fetching for dropdowns |
| 106 | +│ │ ├── keys/ # Config management (CRUD operations) |
| 107 | +│ │ ├── token/ # Token management & caching |
| 108 | +│ │ └── call/ # Quick API endpoint calls |
| 109 | +├── components/ # React components |
| 110 | +│ ├── QuickApiExplorer.tsx # Quick API exploration interface |
| 111 | +│ ├── QuickApiModal.tsx # API endpoint execution modal |
| 112 | +│ ├── SmartParameterForm.tsx # Smart parameter detection & forms |
| 113 | +│ ├── CodeViewer.tsx # Recipe viewer with Config tab |
| 114 | +│ ├── AuthRecipeCard.tsx # Authentication recipe card |
| 115 | +│ └── RecipeCard.tsx # Standard recipe cards |
| 116 | +├── lib/ # Utilities |
| 117 | +│ ├── smartParameters.ts # Parameter detection logic |
| 118 | +│ ├── keyStorage.ts # Encrypted config storage |
| 119 | +│ └── recipeScanner.ts # Recipe discovery & analysis |
| 120 | +└── recipes/ # Self-contained recipe files (copied from sigma-api-recipes) |
| 121 | + ├── connections/ # Connection-related recipes |
| 122 | + ├── members/ # Member management recipes |
| 123 | + ├── teams/ # Team management recipes |
| 124 | + ├── workbooks/ # Workbook operations |
| 125 | + ├── embedding/ # Embedding examples |
| 126 | + └── get-access-token.js # Authentication helper |
| 127 | +``` |
| 128 | + |
| 129 | +For setup instructions and API credential creation, visit the QuickStart: [Sigma REST API Recipes](https://quickstarts.sigmacomputing.com/guide/developers_api_code_samples/index.html?index=..%2F..index#0) |
0 commit comments