#APIResource

Un recurso de API genérico para realizar solicitudes basadas en URLs, adecuado para cualquier interfaz HTTP. Hereda de la clase base FlowResource y la extiende con configuración de solicitudes y el método refresh(). A diferencia de MultiRecordResource y SingleRecordResource, APIResource no depende de un nombre de recurso; realiza solicitudes directamente por URL, lo que lo hace ideal para interfaces personalizadas, APIs de terceros y otros escenarios.

Método de creación: ctx.makeResource('APIResource') o ctx.initResource('APIResource'). Debe llamar a setURL() antes de su uso. En el contexto de RunJS, ctx.api (APIClient) se inyecta automáticamente, por lo que no es necesario llamar a setAPIClient manualmente.

#Escenarios de uso

#Capacidades de la clase base (FlowResource)

Todos los recursos poseen lo siguiente:

#Configuración de la solicitud

#Formato de URL

• Estilo de recurso: Admite la abreviatura de recursos de NocoBase, como users:list o posts:get, que se concatenará con la baseURL.
• Ruta relativa: Por ejemplo, /api/custom/endpoint, concatenada con la baseURL de la aplicación.
• URL completa: Utilice direcciones completas para solicitudes de origen cruzado; el destino debe tener configurado CORS.

#Obtención de datos

#Ejemplos

#Solicitud GET básica

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

#URL con estilo de recurso

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

#Solicitud POST (con cuerpo de solicitud)

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

#Escuchar el evento refresh

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

#Manejo de errores

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 solicitud ha fallado');
}

#Encabezados de solicitud personalizados

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

#Consideraciones

• Dependencia de ctx.api: En RunJS, ctx.api es inyectado por el entorno; generalmente no es necesario llamar a setAPIClient manualmente. Si se utiliza en un escenario sin contexto, debe configurarlo usted mismo.
• Refresh equivale a la solicitud: refresh() inicia una solicitud basada en la configuración actual; el método, los parámetros, los datos, etc., deben configurarse antes de la llamada.
• Los errores no actualizan los datos: En caso de fallo, getData() mantiene su valor anterior; la información del error se puede recuperar a través de getError().
• Frente a ctx.request: Utilice ctx.request() para solicitudes simples de una sola vez; utilice APIResource cuando se requiera gestión de datos reactivos, eventos y estado de error.

#Relacionado

• ctx.resource - La instancia de recurso en el contexto actual.
• ctx.initResource() - Inicializar y vincular a ctx.resource.
• ctx.makeResource() - Crear una nueva instancia de recurso sin vincularla.
• ctx.request() - Solicitud HTTP general, adecuada para llamadas simples y puntuales.
• MultiRecordResource - Orientado a colecciones/listas, admite CRUD y paginación.
• SingleRecordResource - Orientado a registros individuales.