docs/docs/en/runjs/context/request.md
Sends authenticated HTTP requests from RunJS. Requests use the app’s baseURL, token, locale, role, etc., and the app’s interceptors and error handling.
Use whenever RunJS needs to call a remote HTTP API: JSBlock, JSField, JSItem, JSColumn, event flow, linkage, JSAction, etc.
request(options: RequestOptions): Promise<AxiosResponse<any>>;
RequestOptions extends Axios AxiosRequestConfig:
type RequestOptions = AxiosRequestConfig & {
skipNotify?: boolean | ((error: any) => boolean); // Skip global error toast on failure
skipAuth?: boolean; // Skip auth redirect (e.g. 401 → login)
};
| Parameter | Type | Description |
|---|---|---|
url | string | URL. Supports resource style (e.g. users:list, posts:create) or full URL |
method | 'get' | 'post' | 'put' | 'patch' | 'delete' | HTTP method; default 'get' |
params | object | Query params (serialized to URL) |
data | any | Request body for post/put/patch |
headers | object | Custom headers |
skipNotify | boolean | (error) => boolean | When true or function returns true, no global error message |
skipAuth | boolean | When true, 401 etc. do not trigger auth redirect (e.g. to login) |
NocoBase resource API supports resource:action shorthand:
| Format | Description | Example |
|---|---|---|
collection:action | Single-table CRUD | users:list, users:get, users:create, posts:update |
collection.relation:action | Association (need resourceOf or primary key in URL) | posts.comments:list |
Relative URLs are joined with the app baseURL (usually /api). For cross-origin, use a full URL and ensure CORS on the target.
Returns Axios response. Common usage:
response.data: response bodydata.data (records) + data.meta (pagination)data.data as one recordconst { data } = await ctx.request({
url: 'users:list',
method: 'get',
params: { pageSize: 10, page: 1 },
});
const rows = Array.isArray(data?.data) ? data.data : [];
const meta = data?.meta;
const res = await ctx.request({
url: 'users:create',
method: 'post',
data: { nickname: 'John', email: '[email protected]' },
});
const newRecord = res?.data?.data;
const res = await ctx.request({
url: 'users:list',
method: 'get',
params: {
pageSize: 20,
sort: ['-createdAt'],
filter: { status: 'active' },
},
});
const res = await ctx.request({
url: 'some:action',
method: 'get',
skipNotify: true,
});
const res2 = await ctx.request({
url: 'some:action',
method: 'get',
skipNotify: (err) => err?.name === 'CanceledError',
});
For other domains, the target must allow CORS. For its own token, pass in headers:
const res = await ctx.request({
url: 'https://api.example.com/v1/data',
method: 'get',
});
const res2 = await ctx.request({
url: 'https://api.other.com/items',
method: 'get',
headers: {
Authorization: 'Bearer <target-token>',
},
});
const { data } = await ctx.request({
url: 'users:list',
method: 'get',
params: { pageSize: 5 },
});
const rows = Array.isArray(data?.data) ? data.data : [];
ctx.render([
'<div style="padding:12px">',
'<h4>' + ctx.t('User list') + '</h4>',
'<ul>',
...rows.map((r) => '<li>' + (r.nickname ?? r.username ?? '') + '</li>'),
'</ul>',
'</div>',
].join(''));
skipNotify: true to handle yourself.ctx.request)