Files
xpack-mcp/frontend/docs/api.md
T
2025-10-16 17:35:45 +08:00

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

  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
// 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 servers
  • 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:

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);
  });
});