Skip to main content

API Integration

Developer Beginner

Make API calls using built-in utilities and React Query.

For a concise list of everything exported from 'ez-console' (including client, request, api, and hooks), see Package exports (index.ts).

API Utilities​

import { apiGet, apiPost, apiPut, apiDelete } from 'ez-console';

// GET request
const products = await apiGet('/products');

// POST request
const newProduct = await apiPost('/products', {
  name: 'Product Name',
  price: 99.99,
});

// PUT request
const updated = await apiPut(`/products/${id}`, {
  name: 'New Name',
});

// DELETE request
await apiDelete(`/products/${id}`);

Paths are resolved against the shared Axios instance’s baseURL (/api in the framework client).

Aggregated api client​

ez-console exports a generated api object built by merging the OpenAPI modules (authorization, base, oauth, system, tasks, …) into one flat namespace of async functions (see Package exports → api).

import { api } from 'ez-console';

// Example: names depend on code generation — use IDE completion
const user = await api.getCurrentUser();

If you maintain a fork of the framework web app, you can alternatively import api from '@/service/api' for a nested layout (api.authorization.*, api.system.*). Only the flat merged api is part of the public 'ez-console' entry.

client, request, SSE, and errors​

Lower-level exports from 'ez-console':

SymbolRole
clientShared axios instance: baseURL /api, JSON defaults, interceptors for Bearer token, optional X-Scope-OrgID, Accept-Language, JSON envelope unwrap (code === "0"), pagination shape, and 401 redirect to login.
requestTyped helper on top of client / fetch: supports normal JSON, requestType: 'form' (multipart), requestType: 'sse' (returns ReadableStream), and responseType blob / text / arraybuffer.
fetchSSEfetch wrapper returning response.body as a stream for SSE endpoints.
ApiErrorSubclass of Error with string code; typical rejection type from the error interceptor when the server returns JSON errors.

Example: streaming with auth headers (handled automatically when using request with requestType: 'sse'):

import { request } from 'ez-console';

const stream = await request('/api/your/sse/endpoint', {
  method: 'POST',
  requestType: 'sse',
  data: { prompt: 'hello' },
  signal: controller.signal,
});
// ReadableStream<Uint8Array> — consume per your protocol

Using with React Query (ahooks)​

import { useRequest } from 'ahooks';
import { apiGet, apiPost } from 'ez-console';

function ProductList() {
  // Fetch data
  const { data, loading, error } = useRequest(() => apiGet('/products'));
  
  // Mutation
  const { run: createProduct, loading: creating } = useRequest(
    (values) => apiPost('/products', values),
    {
      manual: true,
      onSuccess: () => {
        message.success('Product created');
      },
    }
  );
  
  if (loading) return <Spin />;
  if (error) return <Alert message="Error loading products" />;
  
  return (
    <div>
      {data.map(product => (
        <div key={product.id}>{product.name}</div>
      ))}
    </div>
  );
}

With Pagination​

const { data, loading } = useRequest(
  ({ current, pageSize }) => apiGet('/products', {
    params: { page: current, page_size: pageSize }
  }),
  {
    defaultParams: [{ current: 1, pageSize: 10 }],
  }
);

// Response format:
// {
//   code: "0",
//   data: [...],
//   total: 100,
//   current: 1,
//   page_size: 10
// }

Error Handling​

Successful responses are already normalized by interceptors (envelope unwrap). Failures from the default JSON path are often instances of ApiError (import { ApiError } from 'ez-console'), not raw Axios errors:

import { ApiError, apiGet } from 'ez-console';
import { useRequest } from 'ahooks';
import { message } from 'antd';

const { data, error } = useRequest(() => apiGet('/products'), {
  onError: (err: unknown) => {
    if (err instanceof ApiError) {
      message.error(`${err.code}: ${err.message}`);
      return;
    }
    message.error('Request failed');
  },
});

For api.* and request, the same interceptors apply unless you bypass client intentionally.

Request Interceptors​

Requests automatically include:

  • Authorization header (Bearer token)
  • Content-Type: application/json
  • CSRF token (if configured)

Response Interceptors​

Responses are automatically handled:

  • Token refresh on 401
  • Error message extraction
  • Loading state management

Next Steps​