Files
xpack-mcp/frontend/docs/api.md
T

476 lines
9.7 KiB
Markdown

# 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<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`:
```typescript
// 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`:
```typescript
// 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`:
```typescript
// 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
```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<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
```typescript
interface APIError {
message: string;
code: string;
status: number;
details?: any;
}
```
### Error Handling Pattern
```typescript
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
```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 <ProductDetail service={service} />
}
```
### Client-side Data
For dynamic content and real-time updates:
```typescript
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 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);
});
});
```