atBB Bruno API Collections#

This directory contains Bruno API collections for testing and documenting the atBB forum API.

Structure#

bruno/
├── environments/           # Environment configurations
│   ├── local.bru          # Local development (default)
│   └── dev.bru            # Development server
└── AppView API/           # AppView API endpoints
    ├── Health/            # Health check
    ├── Auth/              # OAuth authentication flow
    ├── Forum/             # Forum metadata
    ├── Categories/        # Category management
    ├── Topics/            # Topic (thread) operations
    └── Posts/             # Post (reply) operations

Getting Started#

1. Install Bruno#

Download and install Bruno from usebruno.com or via package manager:

# macOS (Homebrew)
brew install bruno

# Arch Linux
yay -S bruno-bin

# Or download from GitHub releases

2. Open the Collection#

1. Launch Bruno
2. Click "Open Collection"
3. Navigate to /path/to/atbb-monorepo/bruno
4. Select the bruno folder

3. Start Your Local Servers#

# In the monorepo root
pnpm dev

This will start:

• AppView API at http://localhost:3000
• Web UI at http://localhost:3001

4. Configure Environment Variables#

The local environment is pre-configured for local development. Update these variables in environments/local.bru as needed:

• appview_url - AppView API base URL (default: http://localhost:3000)
• web_url - Web UI base URL (default: http://localhost:3001)
• forum_did - Forum DID from your .env file
• user_handle - Your AT Protocol handle for testing auth (e.g., user.bsky.social)
• topic_id - A valid topic ID for testing topic retrieval

API Overview#

Health Check#

• GET /api/healthz - Service health status

Authentication#

OAuth flow using @atproto/oauth-client-node:

1. GET /api/auth/login?handle=user.bsky.social - Initiate login
2. GET /api/auth/callback - OAuth callback (handled by PDS redirect)
3. GET /api/auth/session - Check current session
4. GET /api/auth/logout - Logout and revoke tokens

Note: OAuth login requires a browser flow. Use the Web UI for interactive testing.

Forum Data#

• GET /api/forum - Get forum metadata
• GET /api/categories - List all categories
• GET /api/topics/:id - Get topic with replies
• POST /api/topics - Create new topic (requires auth)
• POST /api/posts - Create reply (requires auth)

Testing Authenticated Endpoints#

Authenticated endpoints (POST /api/topics, POST /api/posts) require a valid session cookie (atbb_session). Bruno's cookie jar will automatically store and send cookies.

To test authenticated endpoints:

1. Use your browser to log in via the Web UI at http://localhost:3001
2. Use browser dev tools to copy the atbb_session cookie value
3. In Bruno, go to the collection settings and add a header:

   Cookie: atbb_session=<your-cookie-value>
   

Or use Bruno's cookie management to manually set the cookie.

Environment Variables Reference#

Bruno Features Used#

• Environments - Switch between local/dev with one click
• Variables - {{variable}} syntax for reusable values
• Assertions - Automated response validation
• Documentation - Inline docs for each endpoint
• Request chaining - Variables can be set from responses (not used yet, but available)

Tips#

• Use the Environments dropdown in Bruno to switch between local and dev
• Each request includes a Docs tab explaining the endpoint
• Assertions will automatically validate responses (green checkmark = passed)
• Browse requests by category in the left sidebar
• Requests are plain text files — they're versioned in git!

Adding New Endpoints#

When you add new API routes:

1. Create a new .bru file in the appropriate folder
2. Follow the existing format (meta, get/post, headers, body, docs)
3. Use environment variables ({{appview_url}}) for URLs
4. Add assertions to validate responses
5. Commit the file — it's part of your API documentation!

Resources#

• Bruno Documentation
• AT Protocol Docs
• atBB Project Plan