Docs/API Publique/Relations (Populate)

Relations et Populate

Chargez automatiquement les donnees liees avec le parametre populate. Utilisez le nom du champ (local_key) pour specifier les relations a charger.

Comment fonctionne populate

Quand vous avez une relation entre deux collections (ex: commandes → clients), le champ de relation contient normalement un UUID. Avec populate, ce champ est automatiquement remplace par l'objet complet.

Sans populate :

{
  "id": "cmd-001",
  "id_client": "cli-123",
  "montant": 150.00
}

Avec ?populate=id_client :

{
  "id": "cmd-001",
  "id_client": {
    "id": "cli-123",
    "nom": "Dupont",
    "email": "dupont@mail.com"
  },
  "montant": 150.00
}

Syntaxe

Regle importante : Utilisez le nom du champ (local_key) tel qu'il apparait dans vos donnees, pas le nom de la relation.

# Une seule relation
?populate=id_client

# Plusieurs relations (separees par virgule)
?populate=id_client,id_produit,id_categorie

# Exemple complet
curl "https://api.skemacms.com/public/commandes?populate=id_client,id_produit" \
  -H "X-API-Key: pk_live_xxx"

Exemples par type de relation

belongsTo (N:1)

Une commande appartient a un client. Le champ id_client contient l'UUID du client.

GET /public/commandes?populate=id_client

Plusieurs relations

Une commande a un client ET un produit.

GET /public/commandes?populate=id_client,id_produit

Exemple JavaScript complet

const API_KEY = process.env.SKEMA_API_KEY;
const BASE_URL = 'https://api.skemacms.com/public';

const headers = {
  'X-API-Key': API_KEY,
};

// Recuperer les commandes avec client et produit
const getCommandesWithRelations = async () => {
  const params = new URLSearchParams({
    page: '1',
    perPage: '20',
    sort: '-created_at',
    populate: 'id_client,id_produit'
  });

  const res = await fetch(`${BASE_URL}/commandes?${params}`, { headers });
  const data = await res.json();

  // Chaque commande a maintenant id_client et id_produit comme objets
  data.data.forEach(commande => {
    console.log('Client:', commande.id_client?.nom);
    console.log('Produit:', commande.id_produit?.titre);
  });

  return data;
};

// Recuperer un item specifique avec ses relations
const getCommandeById = async (id) => {
  const res = await fetch(
    `${BASE_URL}/commandes/${id}?populate=id_client,id_produit`,
    { headers }
  );
  return res.json();
};

Restrictions

-Seules les collections autorisees par votre cle API peuvent etre populees
-Si une collection cible n'est pas accessible, le champ reste un UUID
-Le populate ne fonctionne qu'avec les champs qui ont une relation definie

← Fonctions avancees MCP →