#APIResource

A generic API resource for making requests based on URLs, suitable for any HTTP interface. It inherits from the FlowResource base class and extends it with request configuration and refresh(). Unlike MultiRecordResource and SingleRecordResource, APIResource does not depend on a resource name; it requests directly by URL, making it suitable for custom interfaces, third-party APIs, and other scenarios.

Creation method: ctx.makeResource('APIResource') or ctx.initResource('APIResource'). You must call setURL() before use. In the RunJS context, ctx.api (APIClient) is automatically injected, so there is no need to call setAPIClient manually.

#Use Cases

#Base Class Capabilities (FlowResource)

All Resources possess the following:

#Request Configuration

#URL Format

• Resource Style: Supports NocoBase resource shorthand, such as users:list or posts:get, which will be concatenated with the baseURL.
• Relative Path: e.g., /api/custom/endpoint, concatenated with the application's baseURL.
• Full URL: Use full addresses for cross-origin requests; the target must have CORS configured.

#Data Fetching

#Examples

#Basic GET Request

const res = ctx.makeResource('APIResource');
res.setURL('/api/custom/endpoint');
res.setRequestParameters({ page: 1, pageSize: 10 });
await res.refresh();
const data = res.getData();

#Resource Style URL

const res = ctx.makeResource('APIResource');
res.setURL('users:list');
res.setRequestParameters({ pageSize: 20, sort: ['-createdAt'] });
await res.refresh();
const rows = res.getData()?.data ?? [];

#POST Request (with Request Body)

const res = ctx.makeResource('APIResource');
res.setURL('/api/custom/submit');
res.setRequestMethod('post');
res.setRequestBody({ name: 'test', type: 'report' });
await res.refresh();
const result = res.getData();

#Listening to the refresh Event

const res = ctx.makeResource('APIResource');
res.setURL('/api/stats');
res.on('refresh', () => {
  const data = res.getData();
  ctx.render(<div>Stats: {JSON.stringify(data)}</div>);
});
await res.refresh();

#Error Handling

const res = ctx.makeResource('APIResource');
res.setURL('/api/may-fail');
try {
  await res.refresh();
  const data = res.getData();
} catch (e) {
  const err = res.getError();
  ctx.message.error(err?.message ?? 'Request failed');
}

#Custom Request Headers

const res = ctx.makeResource('APIResource');
res.setURL('https://api.example.com/data');
res.addRequestHeader('X-Custom-Header', 'value');
res.addRequestParameter('key', 'xxx');
await res.refresh();

#Notes

• ctx.api Dependency: In RunJS, ctx.api is injected by the environment; manual setAPIClient is usually unnecessary. If used in a context-less scenario, you must set it yourself.
• Refresh Means Request: refresh() initiates a request based on the current configuration; method, params, data, etc., must be configured before calling.
• Errors Do Not Update Data: On failure, getData() keeps its previous value; error information can be retrieved via getError().
• Vs ctx.request: Use ctx.request() for simple one-time requests; use APIResource when reactive data, events, and error state management are required.

#Related

• ctx.resource - The resource instance in the current context
• ctx.initResource() - Initialize and bind to ctx.resource
• ctx.makeResource() - Create a new resource instance without binding
• ctx.request() - General HTTP request, suitable for simple one-time calls
• MultiRecordResource - For Collections/lists, supports CRUD and pagination
• SingleRecordResource - For single records