ivip-rest
v1.2.0
Published
O módulo `ivip-rest` é uma poderosa biblioteca Node.js desenvolvida para simplificar e aprimorar o gerenciamento de requisições e respostas de API em aplicações web. Com este módulo, você pode configurar facilmente servidores Express, criar clientes de AP
Downloads
61
Keywords
Readme
ivip-rest (Em Desenvolvimento)
ivip-rest é uma biblioteca Node.js em desenvolvimento para simplificar o gerenciamento de requisições e respostas de API em aplicações web.
Este projeto ainda está em desenvolvimento ativo e não está pronto para uso em produção. Estamos trabalhando duro para trazer recursos incríveis e torná-lo uma ferramenta poderosa para sua aplicação.
Recursos Planejados
- Configuração Simplificada de Servidores Express
- Cliente de API Flexível
- Requisições HTTP Intuitivas
- Gerenciamento de Respostas
- Personalização Avançada
- Facilidade de Uso
Índice
- ivip-rest (Em Desenvolvimento)
Como Começar
Para começar a usar a biblioteca ivip-rest
, siga estas etapas:
Instale a biblioteca via npm ou yarn:
npm install ivip-rest # ou yarn add ivip-rest
Importe os módulos necessários em seu código:
import fetch, { Client, api } from 'ivip-rest';
OU, se quiser usar o cliente no navegador, use o seguinte código:
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/ivip-rest@latest/dist/browser.min.js"></script>
Exemplo de uso:
<script type="text/javascript"> const { Client, fetch } = ivipRest; new Client({ protocol: "https", host: "api.ipify.org", path: "?format=json", }); fetch("/").then(console.log).catch(console.log); </script>
Cliente de API (Client)
O Cliente de API (Client
) é uma parte fundamental da biblioteca ivip-rest
. Ele permite configurar e realizar solicitações HTTP a partir de seu aplicativo para um servidor remoto ou local. Você pode personalizar as configurações do cliente para atender às necessidades específicas de sua aplicação.
Importação
import { Client } from 'ivip-rest';
Construtor
new Client(config: Partial<ClientConfig>)
config
(objeto): Um objeto de configuração que controla o comportamento do cliente.
Propriedades
app
- O objeto
IvipRestApp
associado ao cliente. Fornece informações sobre o aplicativo e configurações gerais.
Métodos
fetch(route: string, config?: Partial<FetchConfig>): Promise<FetchResponse>
route
(string): O caminho da URL para a solicitação.config
(objeto opcional): Um objeto de configuração que permite substituir temporariamente as configurações do cliente para uma solicitação específica.
Realiza uma solicitação HTTP ao servidor especificado pela rota fornecida. Esta função retorna uma promessa (Promise
) que resolve em um objeto de resposta (FetchResponse
), que contém informações sobre a resposta da solicitação.
Configuração
ClientConfig
O objeto de configuração do cliente é usado para personalizar o comportamento do cliente de API. Aqui estão as propriedades aceitáveis no objeto ClientConfig
:
name
(string, opcional): O nome do cliente. Pode ser usado para identificar e recuperar o cliente mais tarde usando a funçãoapi
. Útil quando você deseja configurar vários clientes com diferentes configurações. O nome padrão é'default'
.protocol
(string, opcional): O protocolo usado para a comunicação com o servidor, geralmente'http'
ou'https'
. O padrão é'http'
.host
(string, obrigatório): O host do servidor, por exemplo,'api.example.com'
.port
(number, opcional): A porta usada para a comunicação com o servidor. Se não for especificado, será determinado automaticamente com base no protocolo (80 para HTTP, 443 para HTTPS).path
(string, opcional): O caminho base usado para todas as solicitações. Útil quando seu servidor API está em um subdiretório. O padrão é''
(caminho raiz).params
(string ou objeto, opcional): Parâmetros de consulta que serão anexados a todas as solicitações. Pode ser uma string no formato'param1=value1¶m2=value2'
ou um objeto{ param1: 'value1', param2: 'value2' }
. O padrão é''
(nenhum parâmetro).headers
(objeto, opcional): Cabeçalhos HTTP personalizados que serão enviados com todas as solicitações. O padrão é{}
(nenhum cabeçalho personalizado).requestInterceptor
(função, opcional): Uma função que recebe as informações da solicitação (método, URL, corpo e cabeçalhos) como argumento e pode processar ou modificar essas informações antes que a solicitação seja enviada ao servidor. Útil para adicionar cabeçalhos de autenticação, fazer transformações nos dados de entrada, etc.responseInterceptor
(função, opcional): Uma função que recebe a resposta HTTP (status, dados, cabeçalhos e erro, se houver) como argumento e pode processar ou modificar essa resposta antes que ela seja entregue ao código que fez a solicitação original. Útil para manipular erros comuns, lidar com autenticação, realizar transformações nos dados de saída, etc.adapter
:adapter
permite o tratamento personalizado de solicitações, o que facilita o teste. Retorna uma promessa e fornece uma resposta válida.
Uso
Configuração Inicial
Para começar a usar o Cliente de API, primeiro você deve criar uma instância do cliente com as configurações desejadas. Aqui está um exemplo:
import { Client } from 'ivip-rest';
const myClient = new Client({
//name: 'myApi', // Nome personalizado para o cliente
protocol: 'https', // Protocolo HTTPS
host: 'api.example.com', // Host do servidor
port: 443, // Porta HTTPS padrão
path: '/v1', // Caminho base para todas as solicitações
params: { // Parâmetros de consulta padrão
api_key: 'my-api-key',
locale: 'en_US',
},
headers: { // Cabeçalhos HTTP personalizados
'Authorization': 'Bearer my-auth-token',
},
});
Realização de Solicitações
Com o cliente configurado, você pode realizar solicitações HTTP usando o método fetch
. Aqui estão alguns exemplos:
import fetch from 'ivip-rest';
// Realizar uma solicitação GET simples
const response = await fetch('/resource');
// Realizar uma solicitação POST com corpo de dados
const requestData = { name: 'John', age: 30 };
const response = await fetch('/create', requestData, { method: 'post' });
O objeto response
retornado contém informações sobre a resposta da solicitação, incluindo o status HTTP, os dados da resposta e os cabeçalhos.
Cache Interno
O cliente de API possui um cache interno para armazenar respostas de solicitações com base em seus argumentos. Isso pode ajudar a reduzir as solicitações repetidas ao mesmo recurso. O cache é usado automaticamente, e você não precisa interagir diretamente com ele.
Exemplo Completo
Aqui está um exemplo completo de como usar o Cliente de API ivip-rest
:
import fetch, { Client } from 'ivip-rest';
// Configurar o cliente
const myClient = new Client({
//name: 'myApi',
protocol: 'https',
host: 'api.example.com',
port: 443,
path: '/v1',
params: {
api_key: 'my-api-key',
locale: 'en_US',
},
headers: {
'Authorization': 'Bearer my-auth-token',
},
});
// Realizar uma solicitação GET
const response = await fetch('/resource');
// Verificar a resposta
if (response.status === 200) {
console.log('Dados da resposta:', response.data);
} else {
console.error('Erro na solicitação:', response.error);
}
Lembre-se de configurar seu cliente Client
conforme necessário para atender às necessidades específicas de sua aplicação.
Função api
A função api
é usada para obter um objeto de API configurado a partir de um cliente Client
pré-configurado, exemplo básico:
import { api } from 'ivip-rest';
// Crie um objeto de API personalizado usando o nome pré-configurado em Client
const myApi = api('myApi');
// Use o objeto de API para fazer solicitações
myApi.fetch('/endpoint')
.then(response => {
console.log('Resposta:', response.data);
})
.catch(error => {
console.error('Erro:', error);
});
Assinatura
function api(name: string): {
fetch: typeof fetch;
};
Parâmetros
name
(string): O nome do clienteClient
pré-configurado a ser usado. Este nome deve corresponder a um cliente configurado e armazenado em cache usando o métodoinitializeApp
.
Retorno
- Um objeto que contém uma função
fetch
para fazer solicitações HTTP usando o clienteClient
configurado associado ao nome fornecido.
Uso
A função api
é útil quando você já configurou um cliente Client
e deseja usá-lo para fazer solicitações HTTP. Ela permite que você obtenha um objeto de API com uma função fetch
que usa o cliente configurado. Aqui está um exemplo de uso:
import { api } from 'ivip-rest';
// Obtém um objeto de API configurado a partir do cliente 'myApi'
const myApi = api('myApi');
// Agora você pode usar myApi para fazer solicitações HTTP
const response = await myApi.fetch('/api/data');
Certifique-se de configurar seu cliente Client
corretamente usando initializeApp
antes de usar a função api
.
Função fetch
A função fetch
é usada para fazer solicitações HTTP a um servidor usando o cliente Client
configurado e retornar uma Promise
que resolve em um objeto FetchResponse
, exemplo básico:
import fetch from 'ivip-rest';
// Faça uma solicitação POST com dados de corpo
fetch('/data', {
method: 'POST',
body: {
key: 'value',
},
})
.then(response => {
console.log('Resposta:', response.data);
})
.catch(error => {
console.error('Erro:', error);
});
Assinatura
fetch(this: any, route: string): Fetch;
fetch(this: any, route: string, body: FetchBody): Fetch;
fetch(this: any, route: string, body: FetchBody, config: FetchConfig): Fetch;
fetch(this: any, route: string, config: FetchConfig): Fetch;
Parâmetros
route
(string): O caminho da rota da API que você deseja acessar.body
(opcional): O corpo da solicitação que pode conter dados como JSON ou outros formatos de dados.config
(opcional): Um objeto de configuração que permite especificar opções adicionais para a solicitação, como cabeçalhos personalizados.
Retorno
- Uma
Promise
que resolve em um objetoFetchResponse
contendo informações sobre a resposta da solicitação HTTP.
Uso
A função fetch
tem várias sobrecargas para acomodar diferentes casos de uso:
Solicitação GET simples:
const response = await fetch('/api/data');
Solicitação POST com corpo:
const data = { name: 'John', age: 30 }; const response = await fetch('/api/user', data);
Solicitação POST com corpo e configuração personalizada:
const data = { name: 'John', age: 30 }; const config = { method: 'post', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer <token>', }, expirySeconds: 15 }; const response = await fetch('/api/user', data, config);
Solicitação com configuração personalizada:
const config = { method: 'get', headers: { 'Authorization': 'Bearer <token>', }, }; const response = await fetch('/api/data', config);
Lembre-se de que a função fetch
usa o cliente Client
configurado para fazer a solicitação. Certifique-se de ter configurado o cliente corretamente antes de usar a função fetch
.
Contribuições
Aceitamos contribuições! Sinta-se à vontade para enviar problemas (issues) e pull requests para nos ajudar a melhorar este projeto.
Licença
Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.