#APIResource

Une ressource API générique pour effectuer des requêtes basées sur des URL, adaptée à n'importe quelle interface HTTP. Elle hérite de la classe de base FlowResource et l'étend avec la configuration de requête et la méthode refresh(). Contrairement à MultiRecordResource et SingleRecordResource, APIResource ne dépend pas d'un nom de ressource ; elle effectue des requêtes directement par URL, ce qui la rend adaptée aux interfaces personnalisées, aux API tierces et à d'autres scénarios.

Méthode de création : ctx.makeResource('APIResource') ou ctx.initResource('APIResource'). Vous devez appeler setURL() avant l'utilisation. Dans le contexte RunJS, ctx.api (APIClient) est automatiquement injecté, il n'est donc pas nécessaire d'appeler setAPIClient manuellement.

#Scénarios d'utilisation

#Capacités de la classe de base (FlowResource)

Toutes les ressources possèdent les éléments suivants :

#Configuration de la requête

#Format d'URL

• Style de ressource : Supporte les raccourcis de ressources NocoBase, tels que users:list ou posts:get, qui seront concaténés avec la baseURL.
• Chemin relatif : par ex., /api/custom/endpoint, concaténé avec la baseURL de l'application.
• URL complète : Utilisez des adresses complètes pour les requêtes multi-origines (cross-origin) ; la cible doit avoir le CORS configuré.

#Récupération des données

#Exemples

#Requête GET de base

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

#URL de style ressource

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

#Requête POST (avec corps de requête)

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();

#Écoute de l'événement refresh

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();

#Gestion des erreurs

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 ?? 'La requête a échoué');
}

#En-têtes de requête personnalisés

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();

#Remarques

• Dépendance ctx.api : Dans RunJS, ctx.api est injecté par l'environnement ; l'appel manuel à setAPIClient est généralement inutile. S'il est utilisé dans un scénario sans contexte, vous devez le définir vous-même.
• Refresh signifie requête : refresh() initie une requête basée sur la configuration actuelle ; la méthode, les paramètres, les données, etc., doivent être configurés avant l'appel.
• Les erreurs ne mettent pas à jour les données : En cas d'échec, getData() conserve sa valeur précédente ; les informations d'erreur peuvent être récupérées via getError().
• Comparaison avec ctx.request : Utilisez ctx.request() pour des requêtes simples et uniques ; utilisez APIResource lorsque des données réactives, des événements et une gestion de l'état d'erreur sont requis.

#Liens connexes

• ctx.resource - L'instance de ressource dans le contexte actuel
• ctx.initResource() - Initialiser et lier à ctx.resource
• ctx.makeResource() - Créer une nouvelle instance de ressource sans liaison
• ctx.request() - Requête HTTP générale, adaptée aux appels simples et uniques
• MultiRecordResource - Pour les collections/listes, supporte le CRUD et la pagination
• SingleRecordResource - Pour les enregistrements uniques