DEVELOPER

the macOS app for api routes

theunpartydeveloper

Location: unparty-app/theunpartydeveloper
Status: Active Development
Primary Purpose: Developer tool for testing and monitoring UNPARTY API routes

Overview

theunpartydeveloper is a native macOS application designed to help developers test, monitor, and interact with UNPARTY API endpoints across the ecosystem. It provides a clean SwiftUI interface for sending HTTP requests and viewing responses in real-time, making it an essential tool for UNPARTY developers working with API integrations.

Tech Stack

Framework: SwiftUI
Language: Swift 5.0
Database: SwiftData (local persistence)
Platform: macOS 14.0+
Build Tool: Xcode
Testing: Swift Testing + XCTest

Key Features

API Route Testing

Pre-configured Routes: Quick access to common UNPARTY API endpoints
- Welcome endpoint (theunpartyapp.json)
- Basic routes
- Auth routes
- Admin routes
- User routes
HTTP Method Support: GET requests (extensible for POST, PUT, DELETE)
Real-time Response Viewing: See API responses immediately in a scrollable view
Navigation-based Interface: Clean, native macOS experience with NavigationView

Developer Experience

Quick Setup: No configuration needed - routes are pre-loaded
Visual Method Indicators: Color-coded HTTP methods (GET = green)
Response Formatting: Human-readable response display
Error Handling: Clear error messages for failed requests
Native macOS Design: Follows Apple Human Interface Guidelines

Data Persistence

SwiftData Integration: Local storage for future enhancements
Item Model: Extensible data model for logging and history

Architecture

Code

macOS App (SwiftUI)
├── UNPARTYAPIApp (Main App)
│   ├── SwiftData Container
│   └── Window Group
├── Views
│   ├── ContentView (Route List)
│   └── RouteDetailView (Request/Response UI)
├── Models
│   ├── APIRoute (Route Definition)
│   └── Item (SwiftData Model)
└── Tests
    ├── UNPARTYAPITests (Unit Tests)
    └── UNPARTYAPIUITests (UI Tests)

Data Model

APIRoute

swift

struct APIRoute: Identifiable {
    let id: UUID
    let name: String      // Human-readable route name
    let method: String    // HTTP method (GET, POST, etc.)
    let url: String       // Full API endpoint URL
}

Item (SwiftData)

swift

@Model
final class Item {
    var timestamp: Date
    // Extensible for future logging/history features
}

Getting Started

Prerequisites

macOS: 14.0 (Sonoma) or later
Xcode: Latest version with Swift 5.0+ support
Apple Developer Account: For code signing (Team ID: LL65276K8C)

Installation

Clone the repository:

bash

git clone https://github.com/unparty-app/theunpartydeveloper.git
cd theunpartydeveloper

Open in Xcode:
bash
open UNPARTYAPI.xcodeproj
Build and Run:
- Select the UNPARTYAPI scheme
- Choose a macOS destination
- Press Cmd + R to build and run

Usage

Launch the application
Select a route from the list (e.g., "Welcome", "Basic Routes")
View route details including the full URL
Click "Send GET Request" to execute the API call
View the response in the scrollable response area

API Endpoints

The application comes pre-configured with these UNPARTY ecosystem endpoints:

Route Name	Method	Endpoint
Welcome	GET	`https://unparty-query-api.vercel.app/theunpartyapp.json`
Basic Routes	GET	`https://founders.unparty.app/api/basic`
Auth Routes	GET	`https://founders.unparty.app/api/auth`
Admin Routes	GET	`https://founders.unparty.app/admin`
User Routes	GET	`https://founders.unparty.app/api/users`

Integration Points

UNPARTY Ecosystem

theunpartyapp: Tests web platform API endpoints
Vercel Deployment: Connects to production APIs on Vercel
founders.unparty.app: Primary API testing target

External Services

URLSession: Native HTTP client for API requests
SwiftData: Local data persistence
App Sandbox: Enabled with network access permissions

Security

Sandboxing

The application runs in an App Sandbox with the following permissions:

✅ Outgoing Network Connections: Required for API requests
✅ Incoming Network Connections: Enabled for future features
✅ Hardened Runtime: Enhanced security
❌ Audio Input: Disabled
❌ Camera: Disabled
❌ Location: Disabled
❌ Contacts: Disabled

Network Security

HTTPS-only endpoints (TLS 1.2+)
No credentials stored in the application
No sensitive data persistence

Testing

Running Tests

bash

# Run all tests
xcodebuild test -scheme UNPARTYAPI -destination 'platform=macOS'

# Run unit tests only
xcodebuild test -scheme UNPARTYAPI -destination 'platform=macOS' -only-testing:UNPARTYAPITests

# Run UI tests only
xcodebuild test -scheme UNPARTYAPI -destination 'platform=macOS' -only-testing:UNPARTYAPIUITests

Test Coverage

Unit Tests: UNPARTYAPITests/ - Swift Testing framework
UI Tests: UNPARTYAPIUITests/ - XCTest UI automation
Launch Performance Tests: Measures application startup time

Business Value

ABOUT: Understanding Developer Workflow

API Discovery: Helps developers understand available UNPARTY endpoints
Response Inspection: See exactly what data each endpoint returns
Error Diagnosis: Quickly identify API issues during development

BUILD: Enabling Development

Rapid Prototyping: Test API integrations before writing production code
Development Velocity: No need for curl or Postman - native macOS tool
Documentation Aid: Serves as living documentation of API endpoints

CONNECT: Team Collaboration

Shared Tool: Common interface for all UNPARTY developers
Consistent Testing: Standardized way to verify API functionality
Onboarding: New developers can explore APIs through the app

Relationship to UNPARTY Ecosystem

Primary Connections

Data Flow

Developer opens theunpartydeveloper
Selects route from pre-configured list
Sends request to UNPARTY API endpoint
Views response in native UI
Iterates on API integration in other projects

Supporting Repositories

theunpartyapp: Primary API source being tested
theunpartyrunway: May use this tool for API health checks
theunpartycrawler: Could test analytics API endpoints

Development

Project Structure

Code

theunpartydeveloper/
├── UNPARTYAPI/                    # Main application target
│   ├── UNPARTYAPIApp.swift       # App entry point
│   ├── ContentView.swift          # Route list UI
│   ├── RouteDetailView.swift     # Request/response UI
│   ├── Item.swift                 # SwiftData model
│   ├── Assets.xcassets/           # App icons and images
│   ├── Preview Content/           # Xcode previews
│   └── UNPARTYAPI.entitlements   # App permissions
├── UNPARTYAPITests/              # Unit tests
│   └── UNPARTYAPITests.swift
├── UNPARTYAPIUITests/            # UI automation tests
│   ├── UNPARTYAPIUITests.swift
│   └── UNPARTYAPIUITestsLaunchTests.swift
├── UNPARTYAPI.xcodeproj/         # Xcode project
└── README.md                      # This file

Code Style

Swift 5.0 conventions
SwiftUI declarative syntax
MVVM pattern (implicit in SwiftUI)
Comprehensive error handling

Adding New Routes

To add a new API route to test:

swift

// In ContentView.swift, add to the routes array:
@State private var routes: [APIRoute] = [
    // ... existing routes ...
    APIRoute(
        name: "New Route Name",
        method: "GET",  // or "POST", "PUT", "DELETE"
        url: "https://your-endpoint.unparty.app/api/path"
    )
]

Extending HTTP Methods

The current implementation supports GET requests. To add POST, PUT, DELETE:

swift

// In RouteDetailView.swift, modify sendRequest():
request.httpMethod = method
if method == "POST" {
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    // Add request body
    request.httpBody = jsonData
}

Roadmap

Planned Features

Request History: Save and replay previous requests
Custom Headers: Add authentication and custom headers
POST/PUT/DELETE Support: Full HTTP method coverage
Request Body Editor: JSON/form data input
Response Formatting: Pretty-print JSON responses
Collection Management: Organize routes into collections
Environment Variables: Switch between dev/staging/prod
Export/Import: Share route collections with team

Future Integration

CloudKit sync for shared route collections
Integration with theunpartyrunway for automated testing
GraphQL support for theunpartyapp queries
WebSocket connection testing

Contributing

Development Workflow

Create a feature branch:

bash

git checkout -b feature/your-feature-name

Make changes and test:

bash

# Build
xcodebuild build -scheme UNPARTYAPI

# Test
xcodebuild test -scheme UNPARTYAPI -destination 'platform=macOS'

Commit with clear messages:

bash

git commit -m "feat: Add POST request support"

Push and create pull request:
bash
git push origin feature/your-feature-name

Code Review Checklist

Code follows Swift conventions
UI follows macOS Human Interface Guidelines
Tests added for new functionality
No hardcoded credentials or secrets
Sandbox permissions justified and minimal
Documentation updated (README, code comments)

Documentation

Related Files

CLAUDE.md: AI assistant guidance for working with this project
UNPARTYAPI.entitlements: macOS sandbox permissions
Info.plist: Generated - application metadata

External Resources

Troubleshooting

Common Issues

Issue: "Could not create ModelContainer"

Solution: Ensure SwiftData schema is correctly defined in UNPARTYAPIApp.swift

Issue: Network requests fail with SSL error

Solution: Verify all endpoints use HTTPS (required by App Transport Security)

Issue: Build fails with code signing error

Solution: Update development team in Xcode project settings or use automatic signing

Issue: Response shows "No data received"

Solution: Check that API endpoint is accessible and returning data

Performance

App Size

Bundle Size: ~2-3 MB (minimal SwiftUI app)
Memory Usage: ~50-100 MB (typical for macOS SwiftUI app)
Startup Time: < 1 second

Network Performance

Requests use URLSession default configuration
No caching implemented (future enhancement)
Timeout: 60 seconds default

What problem does this repo solve?
Provides a native macOS tool for testing UNPARTY API endpoints without external tools like Postman or curl.
Who is the primary user?
UNPARTY developers working on API integrations across the ecosystem.
What tech stack does it use?
SwiftUI + SwiftData on macOS 14.0+, built with Xcode.
How does it integrate with other repos?
Tests API endpoints from theunpartyapp and could be used by theunpartyrunway for monitoring.
Is it actively developed or archived?
Active development - created September 2024.
What are the key features/capabilities?
Pre-configured API routes, HTTP request execution, real-time response viewing, native macOS UI.
What external services does it depend on?
UNPARTY APIs hosted on Vercel (founders.unparty.app, unparty-query-api.vercel.app).
How does it align with ABOUT → BUILD → CONNECT?
ABOUT: Helps understand APIs; BUILD: Enables rapid development; CONNECT: Standardizes team testing.
What business value does it provide?
Accelerates development by providing instant API testing and validation in a native tool.
How does it protect creator ownership, privacy, and cost-sensitivity?
No data leaves the local machine except HTTP requests, no telemetry, no external dependencies, minimal resource usage.

Status: ✅ Active Development
Focus: Empowering UNPARTY developers with native API testing tools while maintaining security and privacy.