9.7 KiB
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
# API Endpoints
NEXT_PUBLIC_API_URL=http://localhost:8080
Base API Client
The application uses a custom fetch wrapper and RPC client:
// 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:
// Fetch all MCP servers
export async function fetchServices(): Promise<ServiceData[]>;
// Fetch service by ID
export async function fetchServiceById(id: string): Promise<ServiceData | null>;
// Search services with filters
export async function searchServices(
filters: ServiceFilters
): Promise<ServiceData[]>;
Authentication Service
Located in src/services/authService.ts:
// User login
export async function loginUser(
credentials: LoginCredentials
): Promise<AuthResponse>;
// Admin login
export async function adminLogin(
credentials: AdminCredentials
): Promise<AdminAuthResponse>;
// Token validation
export async function validateToken(token: string): Promise<boolean>;
// Logout
export async function logout(): Promise<void>;
User Service
Located in src/services/userService.ts:
// Get user profile
export async function getUserProfile(): Promise<UserProfile>;
// Update user profile
export async function updateUserProfile(
data: UserProfileUpdate
): Promise<UserProfile>;
// Get user dashboard data
export async function getUserDashboard(): Promise<DashboardData>;
Wallet Service
Located in src/services/walletService.ts:
// Get wallet balance
export async function getWalletBalance(): Promise<WalletBalance>;
// Get transaction history
export async function getTransactions(
filters?: TransactionFilters
): Promise<Transaction[]>;
// Create payment
export async function createPayment(
data: PaymentData
): Promise<PaymentResponse>;
Data Types
Service Data
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
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
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:
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:
// src/store/authStore.ts
interface AuthStore {
user: User | null;
token: string | null;
isAuthenticated: boolean;
login: (credentials: LoginCredentials) => Promise<void>;
logout: () => void;
refreshToken: () => Promise<void>;
}
export const useAuthStore = create<AuthStore>((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
interface APIError {
message: string;
code: string;
status: number;
details?: any;
}
Error Handling Pattern
import { toast } from "react-hot-toast";
async function handleAPICall<T>(apiCall: () => Promise<T>): Promise<T | null> {
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
- User submits login form
- Call
loginUserAPI - Store token and user data in auth store
- Redirect to dashboard or intended page
// 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:
// 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 <ProductDetail service={service} />
}
Client-side Data
For dynamic content and real-time updates:
function ServicesPage() {
const { services, isLoading, error } = useServices()
if (isLoading) return <LoadingSpinner />
if (error) return <ErrorMessage error={error} />
return (
<div>
{services?.map((service) => (
<ServiceCard key={service.id} service={service} />
))}
</div>
)
}
API Endpoints
Public Endpoints
GET /api/web/mcp_services- List all MCP serversPOST /api/web/mcp_service_info- Get service details by IDGET /api/web/categories- List service categoriesPOST /api/auth/login- User loginPOST /api/auth/register- User registrationGET /api/web/featured- Get featured services
Protected Endpoints
GET /api/user/profile- Get user profilePUT /api/user/profile- Update user profileGET /api/user/dashboard- Get user dashboard dataGET /api/user/services- Get user's servicesPOST /api/user/services- Create new serviceGET /api/wallet/balance- Get wallet balanceGET /api/wallet/transactions- Get transaction historyPOST /api/wallet/payment- Create payment
Admin Endpoints
POST /api/admin/login- Admin loginGET /api/admin/users- List all usersPUT /api/admin/users/:id- Update userDELETE /api/admin/users/:id- Delete userGET /api/admin/analytics- Get analytics dataGET /api/admin/services- Get all services for managementPUT /api/admin/services/:id- Update service statusDELETE /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 updatesmarketplace.subscribeToUpdates()- Subscribe to service updatesuser.getDashboard()- Get real-time dashboard datawallet.getBalance()- Get real-time wallet balanceadmin.getAnalytics()- Get real-time analytics data
Rate Limiting
The API implements rate limiting. Handle rate limit errors:
if (error.status === 429) {
toast.error("Too many requests. Please try again later.");
// Implement exponential backoff
}
Caching Strategy
SWR Configuration
// Global SWR config
const swrConfig = {
revalidateOnFocus: false,
revalidateOnReconnect: true,
errorRetryCount: 3,
errorRetryInterval: 5000,
};
Cache Keys
Use consistent cache keys:
// 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
// __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
// __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);
});
});