Requêtes API

SmartCommon fournit le hook useApi qui simplifie les appels API avec gestion automatique de l'authentification JWT, du rafraîchissement de token et de la gestion des erreurs.

Documentation ky (client HTTP utilisé)

Configuration

1. Configurer le Provider

Le ApiProvider doit être configuré dans votre LibConfigProvider : 

// src/appConfig.js

export const appConfig = {
  debug: true,
  api: {
    prefixUrl: import.meta.env.VITE_API_URL,
    timeout: 30000,
    debug: true
  }
};
// src/App.jsx

import { Provider } from '@cap-rel/smartcommon';
import { appConfig } from './appConfig';

export const App = () => {
  return (
    <Provider config={appConfig}>
      <Router />
    </Provider>
  );
};

Utilisation de useApi

Importer le hook

import { useApi } from '@cap-rel/smartcommon';

Structure retournée

Le hook useApi retourne un objet avec les méthodes suivantes :

Méthode Description
login(body, options) Connexion utilisateur, stocke automatiquement les tokens
logout(options) Déconnexion, supprime les tokens
entities(options) Récupère les entités disponibles (avant login)
device(body, options) Enregistre/sélectionne un appareil
public Instance ky pour les requêtes publiques
private Instance ky pour les requêtes authentifiées

Requête de connexion

import { useApi } from '@cap-rel/smartcommon';
import { Input, Button } from '@cap-rel/smartcommon';

export const Login = () => {
  const api = useApi();

  const handleSubmit = async (e) => {
    e.preventDefault();

    const formData = new FormData(e.target);
    const credentials = Object.fromEntries(formData.entries());

    try {
      const user = await api.login({
        ...credentials,
        rememberMe: true
      });

      console.log('Connecté:', user);
    } catch (error) {
      console.error('Erreur de connexion:', error);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <Input name="login" label="Email" type="email" />
      <Input name="password" label="Mot de passe" type="password" />
      <Button type="submit">Connexion</Button>
    </form>
  );
};

Requêtes authentifiées

Pour les requêtes nécessitant une authentification, utilisez api.private : 

import { useApi } from '@cap-rel/smartcommon';
import { useState, useEffect } from 'react';
import { List, ListItem, Spinner } from '@cap-rel/smartcommon';

export const ItemsList = () => {
  const api = useApi();
  const [items, setItems] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchItems = async () => {
      try {
        const data = await api.private.get('items').json();
        setItems(data);
      } catch (error) {
        console.error('Erreur:', error);
      } finally {
        setLoading(false);
      }
    };

    fetchItems();
  }, []);

  if (loading) return <Spinner />;

  return (
    <List>
      {items.map(item => (
        <ListItem key={item.id}>{item.name}</ListItem>
      ))}
    </List>
  );
};

Requêtes POST/PUT/DELETE

const api = useApi();

// POST - Créer
const createItem = async (data) => {
  return api.private.post('items', { json: data }).json();
};

// PUT - Modifier
const updateItem = async (id, data) => {
  return api.private.put(`items/${id}`, { json: data }).json();
};

// DELETE - Supprimer
const deleteItem = async (id) => {
  return api.private.delete(`items/${id}`).json();
};

Requêtes publiques

Pour les requêtes ne nécessitant pas d'authentification : 

const api = useApi();

const fetchPublicData = async () => {
  return api.public.get('public/info').json();
};

Fonctionnalités automatiques

Gestion des tokens

  • Le token d'accès est automatiquement ajouté aux headers des requêtes privées
  • Le token est rafraîchi automatiquement avant expiration
  • En cas d'erreur 401, un refresh est tenté automatiquement

Circuit breaker

  • Protection contre les requêtes en cascade en cas d'erreur serveur
  • Blocage temporaire des requêtes après plusieurs échecs
  • Détection automatique de la connexion internet

Headers automatiques

Chaque requête inclut automatiquement :

  • Authorization: Bearer <token> (requêtes privées)
  • X-DEVICEID: <uuid> (identification de l'appareil)

Méthode classique (fetch natif)

Si vous préférez utiliser fetch directement (non recommandé) :

Documentation API Fetch 

const API_URL = import.meta.env.VITE_API_URL;

const request = {
  method: "POST",
  body: JSON.stringify(data),
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`
  }
};

fetch(`${API_URL}/items`, request)
  .then(response => response.json())
  .then(json => console.log(json))
  .catch(error => console.error(error));

<note tip>Il est recommandé d'utiliser useApi plutôt que fetch natif pour bénéficier de la gestion automatique des tokens et du circuit breaker.</note>

Voir aussi