#APIResource

Eine allgemeine API-Ressource für Anfragen basierend auf URLs, die für beliebige HTTP-Schnittstellen geeignet ist. Sie erbt von der Basisklasse FlowResource und erweitert diese um die Konfiguration von Anfragen sowie die Methode refresh(). Im Gegensatz zu MultiRecordResource und SingleRecordResource hängt die APIResource nicht von einem Ressourcennamen ab, sondern stellt Anfragen direkt über die URL. Dies eignet sich für benutzerdefinierte Schnittstellen, Drittanbieter-APIs und andere Szenarien.

Erstellungsmethode: ctx.makeResource('APIResource') oder ctx.initResource('APIResource'). Vor der Verwendung muss setURL() aufgerufen werden. Im RunJS-Kontext wird ctx.api (APIClient) automatisch injiziert, sodass setAPIClient nicht manuell aufgerufen werden muss.

#Anwendungsfälle

#Funktionen der Basisklasse (FlowResource)

Alle Ressourcen verfügen über folgende Funktionen:

#Konfiguration der Anfrage

#URL-Format

• Ressourcen-Stil: Unterstützt die NocoBase-Kurzschreibweise für Ressourcen, wie users:list oder posts:get, die mit der baseURL kombiniert wird.
• Relativer Pfad: Z. B. /api/custom/endpoint, kombiniert mit der baseURL der Anwendung.
• Vollständige URL: Verwendung vollständiger Adressen für ursprungsübergreifende Anfragen; das Ziel muss CORS konfiguriert haben.

#Datenabruf

#Beispiele

#Einfache GET-Anfrage

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

#URL im Ressourcen-Stil

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

#POST-Anfrage (mit Anfrage-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();

#Auf das refresh-Ereignis hören

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

#Fehlerbehandlung

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 ?? 'Anfrage fehlgeschlagen');
}

#Benutzerdefinierte Anfrage-Header

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

#Hinweise

• Abhängigkeit von ctx.api: In RunJS wird ctx.api von der Umgebung injiziert; ein manuelles setAPIClient ist normalerweise nicht erforderlich. Bei Verwendung in einem kontextlosen Szenario müssen Sie dies selbst festlegen.
• Refresh bedeutet Anfrage: refresh() initiiert eine Anfrage basierend auf der aktuellen Konfiguration; Methode, Parameter, Daten usw. müssen vor dem Aufruf konfiguriert sein.
• Fehler aktualisieren die Daten nicht: Bei einem Fehler behält getData() den vorherigen Wert bei; Fehlerinformationen können über getError() abgerufen werden.
• Vergleich mit ctx.request: Verwenden Sie ctx.request() für einfache, einmalige Anfragen; verwenden Sie APIResource, wenn reaktive Daten, Ereignisse und die Verwaltung des Fehlerzustands erforderlich sind.

#Verwandte Themen

• ctx.resource - Die Ressourcen-Instanz im aktuellen Kontext
• ctx.initResource() - Initialisieren und an ctx.resource binden
• ctx.makeResource() - Eine neue Ressourcen-Instanz erstellen, ohne sie zu binden
• ctx.request() - Allgemeine HTTP-Anfrage, geeignet für einfache, einmalige Aufrufe
• MultiRecordResource - Für Sammlungen/Listen, unterstützt CRUD und Paginierung
• SingleRecordResource - Für einzelne Datensätze