#ctx.request()

Melakukan HTTP request dengan autentikasi di RunJS. Request akan otomatis membawa baseURL, Token, locale, role, dll. dari aplikasi saat ini, dan mengikuti logika interceptor request dan error handling aplikasi.

#Skenario Penggunaan

Semua skenario di RunJS yang perlu melakukan remote HTTP request, seperti JSBlock, JSField, JSItem, JSColumn, event flow, linkage, JSAction, dll.

#Definisi Tipe

request(options: RequestOptions): Promise<AxiosResponse<any>>;

RequestOptions di-extend berdasarkan AxiosRequestConfig dari Axios:

type RequestOptions = AxiosRequestConfig & {
  skipNotify?: boolean | ((error: any) => boolean);  // Apakah skip tip error global saat request gagal
  skipAuth?: boolean;                                 // Apakah skip auth navigation (seperti tidak navigate ke halaman login pada 401)
};

#Parameter Umum

#URL Gaya Resource

API resource NocoBase mendukung bentuk singkat resource:action:

Path relatif akan digabungkan dengan baseURL aplikasi (biasanya /api); cross-domain perlu menggunakan URL lengkap, layanan target perlu mengkonfigurasi CORS.

#Struktur Response

Return value adalah objek response Axios, field umum:

• response.data: response body
• API list biasanya data.data (array record) + data.meta (pagination, dll.)
• API single/create/update biasanya data.data adalah single record

#Contoh

#Query List

const { 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; // Informasi pagination, dll.

#Submit Data

const res = await ctx.request({
  url: 'users:create',
  method: 'post',
  data: { nickname: 'Andi', email: 'andi@example.com' },
});

const newRecord = res?.data?.data;

#Dengan Filter dan Sorting

const res = await ctx.request({
  url: 'users:list',
  method: 'get',
  params: {
    pageSize: 20,
    sort: ['-createdAt'],
    filter: { status: 'active' },
  },
});

#Skip Tip Error

const res = await ctx.request({
  url: 'some:action',
  method: 'get',
  skipNotify: true,  // Tidak menampilkan message global saat gagal
});

// Atau menentukan apakah skip berdasarkan tipe error
const res2 = await ctx.request({
  url: 'some:action',
  method: 'get',
  skipNotify: (err) => err?.name === 'CanceledError',
});

#Cross-Domain Request

Saat menggunakan URL lengkap untuk request domain lain, layanan target perlu mengkonfigurasi CORS untuk mengizinkan asal aplikasi saat ini. Jika API target memerlukan token sendiri, dapat diteruskan melalui 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 <token layanan target>',
  },
});

#Bersama dengan ctx.render untuk Tampilan

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('Daftar User') + '</h4>',
  '<ul>',
  ...rows.map((r) => '<li>' + (r.nickname ?? r.username ?? '') + '</li>'),
  '</ul>',
  '</div>',
].join(''));

#Hal yang Perlu Diperhatikan

• Error handling: request yang gagal akan melempar exception, default akan menampilkan tip error global. Menggunakan skipNotify: true dapat menangkap dan memprosesnya sendiri.
• Autentikasi: request domain yang sama akan otomatis membawa Token, locale, role pengguna saat ini; cross-domain memerlukan target untuk mendukung CORS, dan menyertakan token sesuai kebutuhan di headers.
• Izin resource: request dibatasi oleh ACL, hanya dapat mengakses resource yang dimiliki user saat ini.

#Terkait

• ctx.message - Menampilkan tip ringan setelah request selesai
• ctx.notification - Menampilkan notifikasi setelah request selesai
• ctx.render - Merender hasil request ke interface
• ctx.makeResource - Membangun objek resource, untuk loading data berantai (alternatif dari ctx.request langsung)