#APIResource

Um recurso de API genérico baseado em URL para fazer solicitações, adequado para qualquer interface HTTP. Ele herda da classe base FlowResource e a estende com configurações de solicitação e o método refresh(). Diferente do MultiRecordResource e do SingleRecordResource, o APIResource não depende de um nome de recurso; ele faz a solicitação diretamente pela URL, sendo ideal para interfaces personalizadas, APIs de terceiros e outros cenários.

Formas de criação: ctx.makeResource('APIResource') ou ctx.initResource('APIResource'). Você deve configurar a URL com setURL() antes de usar. No contexto do RunJS, o ctx.api (APIClient) é injetado automaticamente, portanto, não é necessário chamar setAPIClient manualmente.

#Cenários de Uso

#Capacidades da Classe Base (FlowResource)

Todos os Resources possuem:

#Configuração da Solicitação

#Formato da URL

• Estilo de Recurso: Suporta a abreviação de recursos do NocoBase, como users:list ou posts:get, que será concatenada com a baseURL.
• Caminho Relativo: Ex: /api/custom/endpoint, concatenado com a baseURL da aplicação.
• URL Completa: Use endereços completos para solicitações de origem cruzada (cross-origin); o destino deve ter o CORS configurado.

#Busca de Dados

#Exemplos

#Solicitação 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 em 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 ?? [];

#Solicitação POST (com Corpo da Solicitação)

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

#Ouvindo o Evento refresh

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

#Tratamento de Erros

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 ?? 'Falha na solicitação');
}

#Cabeçalhos de Solicitação 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();

#Observações

• Dependência de ctx.api: No RunJS, o ctx.api é injetado pelo ambiente; o setAPIClient manual geralmente é desnecessário. Se usado em um cenário sem contexto, você mesmo deve configurá-lo.
• Refresh é uma Solicitação: O método refresh() inicia uma solicitação baseada na configuração atual; o método, parâmetros, dados, etc., devem ser configurados antes da chamada.
• Erros não Atualizam os Dados: Em caso de falha, o getData() mantém seu valor anterior; as informações de erro podem ser obtidas via getError().
• Comparação com ctx.request: Use ctx.request() para solicitações simples e únicas; use APIResource quando for necessário gerenciamento de dados reativos, eventos e estado de erro.

#Relacionados

• ctx.resource - A instância de recurso no contexto atual
• ctx.initResource() - Inicializa e vincula ao ctx.resource
• ctx.makeResource() - Cria uma nova instância de recurso sem vincular
• ctx.request() - Solicitação HTTP geral, adequada para chamadas simples e únicas
• MultiRecordResource - Voltado para coleções/listas, suporta CRUD e paginação
• SingleRecordResource - Voltado para registros únicos