Skip to main content

Insomnia Setup Guide

Step-by-step guide to set up Insomnia for testing the FishingLog API with Git Sync.

Prerequisites​

  • Insomnia installed (https://insomnia.rest/download)
  • Access to AWS Cognito User Pool (for authentication)
  • Local API running (for local development testing)
  • GitHub repository access

Step 1: Create Project and Connect Git Sync​

Create New Project​

  1. Open Insomnia
  2. Click Create → New Project (or New Design Document)
  3. Name it: FishingLog API
  4. Click Create

Connect Git Sync​

  1. In your new project, click Setup Git Sync (top right)
  2. Click Configure Repository
  3. Authenticate with GitHub (click "Authenticate with GitHub App")
  4. Search for FishingLog.Backend repository
  5. Select it
  6. Important: Set Directory to insomnia/ (not root or empty)
  7. Click Connect

Note: Insomnia may say "We didn't find any Insomnia files" - this is normal. You'll import the workspace file next. If you see "Workspace not found" error, check that the Directory is set to insomnia/ in Git Sync settings.

Step 2: Import Workspace File​

  1. In Insomnia, right-click your project/workspace
  2. Import/Export → Import Data → From File
  3. Navigate to insomnia/FishingLog API-wrk_a06d10d105e24bc68e7dac3e6c97f43b.yaml in your local repository
  4. Click Import
  5. The requests and environments (Local, Staging, Production) will be imported into your project

Note: The filename includes the workspace ID (wrk_...). This is important for Git Sync - don't rename it!

Step 3: Push to Git​

  1. After importing, click Sync button (top right)
  2. Click Push to sync your workspace to Git
  3. Insomnia will create workspace files in your insomnia/ directory
  4. Future changes will sync automatically (if auto-sync is enabled)

Step 4: Configure Environments​

Local Development Environment​

  1. Click the environment dropdown (top left)
  2. Select Local Development
  3. Click the environment name to edit
  4. Verify these variables: 
    base_url: https://localhost:5100
    api_url: https://localhost:5100
    cognito_user_pool_id: us-east-2_TZtGx1T3X
    cognito_client_id: 6i1opt39o2n5h5ihq471l1ev07
    cognito_region: us-east-2
    cognito_domain: us-east-2tztgx1t3x.auth.us-east-2.amazoncognito.com
  5. Click Done

Staging Environment​

  1. Select Staging environment
  2. Variables are pre-configured: 
    base_url: https://api-staging.reelog.app
    api_url: https://api-staging.reelog.app
  3. Same Cognito settings as Local (shared User Pool)

Production Environment​

  1. Select Production environment (ready for when production is deployed)
  2. Variables are pre-configured: 
    base_url: https://api.reelog.app
    api_url: https://api.reelog.app
  3. Same Cognito settings as Local/Staging (shared User Pool)

Step 5: Get Authentication Token​

aws cognito-idp initiate-auth \
  --auth-flow USER_PASSWORD_AUTH \
  --client-id 6i1opt39o2n5h5ihq471l1ev07 \
  --auth-parameters USERNAME=your-username,PASSWORD=your-password \
  --region us-east-2

Copy the AccessToken from the response.

Method 2: Using Cognito Hosted UI​

  1. Visit: https://us-east-2tztgx1t3x.auth.us-east-2.amazoncognito.com/login
  2. Login with your credentials
  3. After redirect, copy the id_token or access_token from the URL hash
  4. Or use browser DevTools → Network → Check the token response

Add Token to Environment​

Important: Use the id_token from the login response, not the access_token. The id_token contains user identity claims and is properly signed for API authentication.

  1. In Insomnia, click Manage Environments (environment dropdown → Manage Environments)
  2. Select your environment (Local or Staging)
  3. Click + to add new variable
  4. Add:
    • Name: access_token
    • Value: Paste the id_token from your login response (not access_token)
  5. Click Done

Note:

  • Use id_token for API authentication (contains user claims and proper audience)
  • access_token is for calling AWS services, not your API
  • Tokens expire after 1 hour. Use the refresh_token to get new tokens.

Step 6: Test the Setup​

Test Health Check (No Auth)​

  1. Select Staging environment
  2. Open Health & Status → Health Check
  3. Click Send
  4. Should return: {"status":"healthy","timestamp":"..."}

Test Authenticated Endpoint​

  1. Make sure access_token is set in your environment
  2. Open Health & Status → Ping (Authenticated)
  3. Click Send
  4. Should return: "pong (secure)"

Test User Endpoint​

  1. Open Users → Get Current User
  2. Click Send
  3. Should return your user information

Step 7: Add More Requests​

Create New Request​

  1. Right-click on a folder (e.g., Users)
  2. Select New Request
  3. Name it (e.g., "Get User Profile")
  4. Set URL: `\{\{ _.api_url \}\}/api/userprofile/me`
  5. Set Method: GET
  6. Add Header:
    • Name: Authorization
    • Value: `Bearer \{\{ _.access_token \}\}`
  7. Click Send to test
  8. Click Save (Ctrl/Cmd + S)

Organize Requests​

  • Create folders for different API sections
  • Use descriptive names
  • Add descriptions to requests
  • Group related requests together

Git Sync Best Practices​

  1. Commit regularly: Commit your Insomnia workspace changes
  2. Don't commit tokens: Use environment variables, not hardcoded tokens
  3. Share environment templates: Keep environment structure in sync
  4. Document custom requests: Add descriptions to requests

Troubleshooting​

"Invalid token" errors​

  • Check that access_token is set in your environment
  • Verify token hasn't expired (Cognito tokens expire after 1 hour)
  • Regenerate token if needed

"Connection refused" (Local)​

  • Make sure your local API is running: dotnet run
  • Check the port matches your environment (5101 for HTTP)

"502 Bad Gateway" (Staging)​

  • Check ECS service is running
  • Verify health checks are passing
  • Check CloudWatch logs for errors

Git Sync Issues​

"Workspace not found" Error

  • Cause: Git Sync directory doesn't match where the workspace file is located
  • Fix:
    1. In Insomnia, go to Preferences → Data → Git Sync
    2. Check the Directory setting
    3. It should be set to insomnia/ (not root / or empty)
    4. If it's wrong, update it to insomnia/ and click Save
    5. Click Pull to sync the workspace file
    6. If still not working, try Disconnect and reconnect Git Sync with directory set to insomnia/

"We didn't find any Insomnia files"

  • This is normal on first setup
  • Import the YAML workspace file manually (Step 2)
  • Then push to Git (Step 3)

"Repository not found"

  • Check repository URL is correct
  • Verify you have access to the repository
  • Try authenticating again

"Authentication failed"

  • Use GitHub App authentication (recommended)
  • Or create Personal Access Token with repo scope
  • Make sure token hasn't expired

Environment Variables Reference​

Available Variables​

  • `\{\{ _.base_url \}\}` - Base API URL
  • `\{\{ _.api_url \}\}` - API URL (same as base_url)
  • `\{\{ _.cognito_user_pool_id \}\}` - AWS Cognito User Pool ID
  • `\{\{ _.cognito_client_id \}\}` - AWS Cognito App Client ID
  • `\{\{ _.cognito_region \}\}` - AWS Region
  • `\{\{ _.cognito_domain \}\}` - Cognito Domain
  • `\{\{ _.access_token \}\}` - JWT Access Token (set manually)

Usage in Requests​

Use variables in URLs and headers:

URL: \{\{ _.api_url \}\}/api/user/me
Header: Bearer \{\{ _.access_token \}\}

Workspace Structure​

The workspace includes comprehensive endpoint coverage:

FishingLog API/
├── Health & Status/
│   ├── Health Check (GET /health) - No auth
│   └── Ping (GET /ping) - Requires auth
├── Authentication/
│   └── Cognito Login (POST /oauth2/token)
├── Users & Profiles/
│   ├── Get Current User
│   ├── Get/Update Profile
│   └── Personal Bests
├── Fishing Logs/
│   ├── Entries (CRUD)
│   ├── Sessions
│   └── Catches
├── Social/
│   ├── Posts (CRUD, Like)
│   ├── Comments
│   └── Friends
├── Gear/
│   ├── Rods, Reels, Lines, Lures (reference)
│   ├── Boats (user-owned)
│   └── Gear Setups
├── Tournaments/
│   └── Registration
├── Spots & Reports/
│   ├── Nearby Spots
│   └── Reports by Location
├── Personal Bests/
├── Circles/
│   ├── Discover
│   ├── Create/Join
│   └── Memberships
├── Events & Clubs/
├── Reference Data/
│   ├── Brands
│   ├── Fish Species
│   └── Regulations
├── Charters/
└── Themes/

Environments:

  • Local Development (https://localhost:5100 for HTTPS, http://localhost:5101 for HTTP)
  • Staging (https://api-staging.reelog.app)
  • Production (https://api.reelog.app) - Ready for future deployment

Next Steps​

  1. ✅ Test all existing requests
  2. ✅ Add requests for your most-used endpoints
  3. ✅ Set up Git Sync for collaboration
  4. ✅ Document any custom requests you add
  5. ✅ Share workspace with team members

Need Help? Check the main README.md or open an issue.