API Development with nfltr + Postman

Expose your local API to the internet in seconds, test it with Postman from anywhere, and share live endpoints with your team — no deployment required.

Why nfltr + Postman?

Every API developer hits the same wall: your API runs on localhost:3000 but you need to:

• Share it with a teammate for review
• Receive webhooks from Stripe, GitHub, or Twilio
• Run Postman collections from a CI server against your local code
• Demo an API to a client without deploying to staging
• Test OAuth callbacks that require a public URL

nfltr creates a public tunnel to your local port. Postman talks to the public URL exactly as if your API were deployed. Together they give you a production-like API testing workflow without leaving localhost.

┌──────────┐      HTTPS       ┌────────────┐      gRPC       ┌───────────┐       HTTP       ┌─────────────┐
│  Postman  │ ───────────────► │  nfltr.xyz  │ ──────────────► │  nfltr    │ ───────────────► │ Your API    │
│  (cloud)  │                  │  (server)   │                 │  (agent)  │                  │ :3000       │
└──────────┘                  └────────────┘                  └───────────┘                  └─────────────┘

Quick Start

1. Start your local API

Any framework — Express, FastAPI, Gin, Rails, Spring Boot, whatever:

# Example: a Node.js API
node server.js   # listens on port 3000

2. Expose it with nfltr

nfltr http 3000

Output:

nfltr v1.0.x starting
  agent-id:     macbook-pro
  server:       grpc.nfltr.xyz:443 (tls=true)
  health:       :29501
  timeout:      60s
  route:        (default) → http://localhost:3000
Using API key authentication

nfltr                  v1.0.x
Agent ID               macbook-pro
Forwarding             https://nfltr.xyz/browse/macbook-pro/ → http://localhost:3000

Waiting for requests... (press Ctrl+C to stop)

Your API is now live at https://nfltr.xyz/browse/macbook-pro/.

3. Use the URL in Postman

1. Open Postman → create a new request
2. Set the URL to https://nfltr.xyz/browse/macbook-pro/api/users
3. Choose method (GET, POST, PUT, DELETE)
4. Add headers and body as needed
5. Click Send

The request travels through nfltr's server, through the gRPC tunnel to your machine, hits localhost:3000/api/users, and the response flows back to Postman. Latency is typically 20–50 ms for a single hop.

Workflow: Share a Live API with Your Team

When working on an API, you want teammates to test it against your running code — not a stale staging deploy.

# Give the tunnel a memorable name
nfltr http 3000 --name payments-api

# Or generate a shareable word-pair URL
nfltr http 3000 --share

Share output (--name payments-api --share):

nfltr                  v1.0.x
Agent ID               payments-api
Forwarding             https://nfltr.xyz/browse/payments-api/ → http://localhost:3000
Share URL              https://swift-bay.nfltr.xyz/

Waiting for requests... (press Ctrl+C to stop)

Hand https://swift-bay.nfltr.xyz/ to your teammate. They paste it into Postman as the base URL and test immediately — no VPN, no deploy, no firewall rules.

Workflow: Postman Collection + nfltr Base URL

Use a Postman environment variable for the base URL so you can switch between local, tunnel, and production without editing every request.

Set up the environment

Use it in requests

GET {{baseUrl}}/api/users
POST {{baseUrl}}/api/orders
PUT {{baseUrl}}/api/orders/{{orderId}}
DELETE {{baseUrl}}/api/users/{{userId}}

When your tunnel changes, update the single variable. All requests adapt.

Switch between environments

Workflow: Receive Webhooks in Postman + nfltr

Third-party services (Stripe, GitHub, Twilio, Razorpay) send webhook callbacks to a URL you configure. During development, that URL needs to reach your local machine.

Step 1: Create a webhook endpoint in your API

# FastAPI example
@app.post("/webhooks/stripe")
async def stripe_webhook(request: Request):
    body = await request.body()
    sig = request.headers.get("stripe-signature")
    # verify & process...
    return {"status": "ok"}

Step 2: Expose with nfltr

nfltr http 8000 --name stripe-hooks

Step 3: Configure Stripe dashboard

Set the webhook URL to:

https://nfltr.xyz/browse/stripe-hooks/webhooks/stripe

Step 4: Monitor in Postman

Use Postman's History sidebar to see every webhook that arrived, or create a Postman Monitor that periodically hits your tunnel endpoint to verify it's healthy.

Step 5: Replay webhooks

Stripe and GitHub let you re-send past webhook events from their dashboards. Every replay hits your local code via the nfltr tunnel, letting you debug handler logic in real time.

Workflow: Multi-Backend Routing

Modern apps have multiple services: an API server, a frontend dev server, a WebSocket server. nfltr routes them all through one tunnel:

nfltr http 3000 \
  --route /api=8080 \
  --route /ws=4000 \
  --name fullstack-app

Set {{baseUrl}} to https://nfltr.xyz/browse/fullstack-app in Postman and organize requests into folders: /api/..., /ws/..., root.

Workflow: Run Postman Collections via Newman (CI)

Use Newman to run your Postman collection against a live nfltr tunnel from CI:

# Terminal 1: start your API + tunnel
nfltr http 3000 --name ci-test-api --duration 600 &

# Terminal 2: run the Postman collection
newman run my-collection.json \
  --env-var "baseUrl=https://nfltr.xyz/browse/ci-test-api" \
  --reporters cli,junit \
  --reporter-junit-export results.xml

This lets your CI pipeline test the real code running on a developer machine (or a CI runner) through a tunnel — useful for integration tests that need real backends.

Workflow: OAuth Callback Testing

OAuth flows redirect to a callback URL. During development, that callback needs to reach your local server:

nfltr http 3000 --name oauth-dev

Configure your OAuth provider (Google, GitHub, Auth0) with:

Callback URL: https://nfltr.xyz/browse/oauth-dev/oauth/google/callback

Now the full OAuth flow works end-to-end from Postman:

1. Postman → GET {{baseUrl}}/login → redirects to Google
2. Google → authenticates → redirects to https://nfltr.xyz/browse/oauth-dev/oauth/google/callback
3. nfltr → tunnels callback to localhost:3000/oauth/google/callback
4. Your API → exchanges code for token → responds

Use Postman's Authorization tab with OAuth 2.0 type for automated token management.

Workflow: Load Testing with Postman + nfltr

# Use a named tunnel for stable URL
nfltr http 3000 --name load-test-api
# Available at: https://nfltr.xyz/browse/load-test-api/

In Postman:

1. Open your collection → Run collection
2. Set iterations (e.g., 100)
3. Set delay (e.g., 100ms)
4. Click Run

nfltr handles concurrent requests through the gRPC tunnel. Monitor your API's response times directly in Postman's run results.

Tips & Best Practices

Use --name for stable URLs

# Bad: URL changes every session
nfltr http 3000

# Good: URL stays the same across sessions
nfltr http 3000 --name my-api

With --name my-api, the URL is always https://nfltr.xyz/browse/my-api/. Save it once in your Postman environment.

Use --share for temporary collaboration

nfltr http 3000 --share

Share URLs like https://swift-bay.nfltr.xyz/ expire after the tunnel disconnects — perfect for a code review session or a quick demo. Unlike --name URLs (path-based via /browse/), share URLs are top-level subdomains for easy sharing.

Set request timeout in Postman

nfltr's default request timeout is 60 seconds. Match it in Postman: Settings → General → Request timeout → 60000 ms.

Use Postman's console for debugging

Open View → Postman Console (⌘+⌥+C) to see raw request/response headers. Useful for verifying nfltr's proxy headers.

Combine with Postman's Mock Server

1. Build your contract in Postman (mock server)
2. Implement the real API locally
3. Expose via nfltr
4. Swap the Postman environment from mock to tunnel URL
5. Run the same collection — validates real vs. mock parity

Complete Example: REST API Development Session

# 1. Start your API
cd my-api && go run . &   # serves on :8080

# 2. Create a stable tunnel
nfltr http 8080 --name my-api

# 3. In Postman, set baseUrl = https://nfltr.xyz/browse/my-api

# 4. Test CRUD operations:
#    POST   {{baseUrl}}/api/users      → Create
#    GET    {{baseUrl}}/api/users       → List
#    GET    {{baseUrl}}/api/users/123   → Read
#    PUT    {{baseUrl}}/api/users/123   → Update
#    DELETE {{baseUrl}}/api/users/123   → Delete

# 5. Share with teammate:
#    "Hey, test my API at https://nfltr.xyz/browse/my-api/"
#    Or: nfltr http 8080 --name my-api --share  (for a short subdomain URL)

# 6. Configure Stripe webhooks:
#    https://nfltr.xyz/browse/my-api/webhooks/stripe

# 7. Run full collection:
#    newman run api-tests.json --env-var "baseUrl=https://nfltr.xyz/browse/my-api"

# 8. Done — Ctrl+C to stop the tunnel

Comparison: nfltr vs. Alternatives for Postman Workflows

Troubleshooting

"Connection refused" in Postman

Your local API isn't running. Verify:

curl http://localhost:3000/

nfltr tunnels to whatever is listening on the port. If nothing is listening, Postman gets a 502 Bad Gateway.

Slow responses (>1s)

Check the hop count: your machine → nfltr.xyz → your machine. If the server is far away, latency adds up.

nfltr logs every request automatically:

[1] GET /api/users → http://localhost:3000/api/users → 200 (1234 bytes, txn=abc123)
[2] POST /api/orders → http://localhost:3000/api/orders → 201 (88 bytes, txn=def456)

Use --verbose to also log heartbeats and full request headers:

nfltr http 3000 --verbose

"503 Service Unavailable" with Retry-After

The agent was recently connected but is temporarily offline. nfltr returns 503 with a Retry-After: 30 header so Postman retries after 30 seconds. If the agent reconnects in time, the next request succeeds.

CORS errors in Postman

Postman doesn't enforce CORS — that's a browser-only restriction. If you see CORS issues, you're testing from a browser, not Postman. Add CORS headers to your API or use Postman directly.

Next Steps

• Go SDK Reference — Embed the nfltr agent in your Go application