# API Integration Guide ## Overview XPack WebUI integrates with the XPack platform APIs to provide marketplace, user management, and admin functionality. The application uses a custom RPC layer alongside traditional REST APIs for optimal performance and real-time capabilities. ## API Configuration ### Environment Variables ```env # API Endpoints NEXT_PUBLIC_API_URL=http://localhost:8080 ``` ### Base API Client The application uses a custom fetch wrapper and RPC client: ```typescript // REST API Client - src/utils/api.ts import { apiRequest } from "@/utils/api"; // GET request const data = await apiRequest("/api/web/mcp_services"); // POST request const result = await apiRequest("/api/web/mcp_service_info", { method: "POST", body: JSON.stringify(payload), }); // RPC Client - src/rpc/client.ts import { rpcClient } from "@/rpc/client"; // RPC method call const result = await rpcClient.call("marketplace.getServices", { category: "ai-tools", limit: 20, }); ``` ## API Services ### Marketplace Service Located in `src/services/marketplaceService.ts`: ```typescript // Fetch all MCP services export async function fetchServices(): Promise; // Fetch service by ID export async function fetchServiceById(id: string): Promise; // Search services with filters export async function searchServices( filters: ServiceFilters ): Promise; ``` ### Authentication Service Located in `src/services/authService.ts`: ```typescript // User login export async function loginUser( credentials: LoginCredentials ): Promise; // Admin login export async function adminLogin( credentials: AdminCredentials ): Promise; // Token validation export async function validateToken(token: string): Promise; // Logout export async function logout(): Promise; ``` ### User Service Located in `src/services/userService.ts`: ```typescript // Get user profile export async function getUserProfile(): Promise; // Update user profile export async function updateUserProfile( data: UserProfileUpdate ): Promise; // Get user dashboard data export async function getUserDashboard(): Promise; ``` ### Wallet Service Located in `src/services/walletService.ts`: ```typescript // Get wallet balance export async function getWalletBalance(): Promise; // Get transaction history export async function getTransactions( filters?: TransactionFilters ): Promise; // Create payment export async function createPayment( data: PaymentData ): Promise; ``` ## Data Types ### Service Data ```typescript interface ServiceData { id: string; name: string; description: string; category: string; author: string; version: string; rating: number; downloads: number; verified: boolean; updatedAt: string; tags: string[]; documentation?: string; pricing?: PricingInfo; } ``` ### User Types ```typescript interface User { id: string; email: string; name: string; avatar?: string; role: "user" | "admin"; createdAt: string; lastLoginAt?: string; } interface UserProfile extends User { preferences: UserPreferences; subscription?: SubscriptionInfo; } ``` ### Authentication ```typescript interface AuthResponse { token: string; user: User; expiresAt: string; } interface LoginCredentials { email: string; password: string; } ``` ## State Management ### API State with SWR The application uses SWR for data fetching and caching: ```typescript import useSWR from "swr"; import { fetchServices } from "@/services/marketplaceService"; function useServices() { const { data, error, isLoading, mutate } = useSWR( "/api/web/mcp_services", fetchServices, { revalidateOnFocus: false, revalidateOnReconnect: true, errorRetryCount: 3, dedupingInterval: 5000, } ); return { services: data, isLoading, error, refresh: mutate, }; } ``` ### Zustand Store Structure The application uses multiple Zustand stores for different domains: ```typescript // src/store/authStore.ts interface AuthStore { user: User | null; token: string | null; isAuthenticated: boolean; login: (credentials: LoginCredentials) => Promise; logout: () => void; refreshToken: () => Promise; } export const useAuthStore = create((set, get) => ({ user: null, token: null, isAuthenticated: false, login: async (credentials) => { const response = await loginUser(credentials); set({ user: response.user, token: response.token, isAuthenticated: true, }); }, logout: () => { set({ user: null, token: null, isAuthenticated: false, }); }, })); ``` ## Error Handling ### API Error Types ```typescript interface APIError { message: string; code: string; status: number; details?: any; } ``` ### Error Handling Pattern ```typescript import { toast } from "react-hot-toast"; async function handleAPICall(apiCall: () => Promise): Promise { try { return await apiCall(); } catch (error) { if (error instanceof APIError) { toast.error(error.message); } else { toast.error("An unexpected error occurred"); } return null; } } ``` ## Authentication Flow ### User Authentication 1. User submits login form 2. Call `loginUser` API 3. Store token and user data in auth store 4. Redirect to dashboard or intended page ```typescript // src/hooks/useLogin.ts export function useLogin() { const { login } = useAuthStore(); const router = useRouter(); const handleLogin = async (credentials: LoginCredentials) => { try { await login(credentials); router.push("/dashboard"); } catch (error) { toast.error("Login failed"); } }; return { handleLogin }; } ``` ### Admin Authentication Similar flow but with admin-specific endpoints and redirects to console. ## Data Fetching Patterns ### Server-Side Rendering (SSR) For marketplace product pages with dynamic content: ```typescript // src/app/marketplace/[id]/page.tsx export default async function ProductPage({ params }: { params: { id: string } }) { // Server-side data fetching const service = await fetchServiceById(params.id) if (!service) { notFound() } return } ``` ### Client-side Data For dynamic content and real-time updates: ```typescript function ServicesPage() { const { services, isLoading, error } = useServices() if (isLoading) return if (error) return return (
{services?.map((service) => ( ))}
) } ``` ## API Endpoints ### Public Endpoints - `GET /api/web/mcp_services` - List all MCP services - `POST /api/web/mcp_service_info` - Get service details by ID - `GET /api/web/categories` - List service categories - `POST /api/auth/login` - User login - `POST /api/auth/register` - User registration - `GET /api/web/featured` - Get featured services ### Protected Endpoints - `GET /api/user/profile` - Get user profile - `PUT /api/user/profile` - Update user profile - `GET /api/user/dashboard` - Get user dashboard data - `GET /api/user/services` - Get user's services - `POST /api/user/services` - Create new service - `GET /api/wallet/balance` - Get wallet balance - `GET /api/wallet/transactions` - Get transaction history - `POST /api/wallet/payment` - Create payment ### Admin Endpoints - `POST /api/admin/login` - Admin login - `GET /api/admin/users` - List all users - `PUT /api/admin/users/:id` - Update user - `DELETE /api/admin/users/:id` - Delete user - `GET /api/admin/analytics` - Get analytics data - `GET /api/admin/services` - Get all services for management - `PUT /api/admin/services/:id` - Update service status - `DELETE /api/admin/services/:id` - Delete service ### RPC Methods The application also supports RPC calls for real-time operations: - `marketplace.getServices(filters)` - Get services with real-time updates - `marketplace.subscribeToUpdates()` - Subscribe to service updates - `user.getDashboard()` - Get real-time dashboard data - `wallet.getBalance()` - Get real-time wallet balance - `admin.getAnalytics()` - Get real-time analytics data ## Rate Limiting The API implements rate limiting. Handle rate limit errors: ```typescript if (error.status === 429) { toast.error("Too many requests. Please try again later."); // Implement exponential backoff } ``` ## Caching Strategy ### SWR Configuration ```typescript // Global SWR config const swrConfig = { revalidateOnFocus: false, revalidateOnReconnect: true, errorRetryCount: 3, errorRetryInterval: 5000, }; ``` ### Cache Keys Use consistent cache keys: ```typescript // Good const CACHE_KEYS = { SERVICES: "/api/services", SERVICE_DETAIL: (id: string) => `/api/services/${id}`, USER_PROFILE: "/api/user/profile", } as const; ``` ## Testing API Integration ### Mock API Responses ```typescript // __tests__/mocks/api.ts export const mockServices: ServiceData[] = [ { id: "1", name: "Test Service", description: "A test service", category: "utility", author: "Test Author", version: "1.0.0", rating: 4.5, downloads: 1000, verified: true, updatedAt: "2024-01-01", tags: ["test"], }, ]; ``` ### API Testing ```typescript // __tests__/api/services.test.ts import { fetchServices } from "@/shared/api/services"; // Mock fetch global.fetch = jest.fn(); describe("Services API", () => { it("fetches services successfully", async () => { (fetch as jest.Mock).mockResolvedValueOnce({ ok: true, json: async () => mockServices, }); const services = await fetchServices(); expect(services).toEqual(mockServices); }); }); ```