jardin/skills/jardin-api-backend/references/backend-api-recipes.md

Backend API Recipes (OpenClaw)

1) Base URL et tests

• Base LAN backend: http://<IP_HOTE>:8060
• Santé: GET /api/health
• Swagger: GET /docs
• ReDoc: GET /redoc

Exemple:

curl http://192.168.1.50:8060/api/health

Réponse attendue:

{"status":"ok"}

2) Règles HTTP à appliquer dans OpenClaw

• JSON: header Content-Type: application/json
• Upload fichier: multipart/form-data sur POST /api/upload
• Timeout conseillé: 15-30s
• Retry réseau conseillé: 2-3
• API sans authentification actuellement (LAN uniquement)

3) Séquence d'ajout recommandée (dépendances)

1. Créer jardin (/api/gardens) -> récupérer garden_id
2. Créer plante (/api/plants) -> récupérer plant_id
3. Créer plantation (/api/plantings) avec garden_id + variety_id=plant_id -> récupérer planting_id
4. Créer tâche (/api/tasks) avec planting_id

4) Endpoints création (payload minimal)

4.1 Jardin

POST /api/gardens

{
  "nom": "serre",
  "type": "serre"
}

4.2 Plante

POST /api/plants

{
  "nom_commun": "Tomate",
  "variete": "Andine Cornue",
  "categorie": "potager"
}

4.3 Plantation

POST /api/plantings

{
  "garden_id": 1,
  "variety_id": 12,
  "quantite": 6,
  "date_plantation": "2026-05-01",
  "statut": "en_cours"
}

4.4 Tâche

POST /api/tasks

{
  "titre": "Arroser tomates serre",
  "description": "Arrosage du matin",
  "planting_id": 8,
  "priorite": "normale",
  "echeance": "2026-05-02",
  "statut": "a_faire"
}

4.5 Outil

POST /api/tools

{
  "nom": "Bêche",
  "categorie": "beche",
  "notice_texte": "Nettoyer la lame après usage."
}

4.6 Astuce

POST /api/astuces

{
  "titre": "Paillage tomate",
  "contenu": "Appliquer 5 cm de paillage après arrosage.",
  "categorie": "plante",
  "tags": "[\"tomate\",\"paillage\"]",
  "mois": "[4,5,6]"
}

5) Mise à jour (PUT/PATCH)

5.1 Mise à jour standard (PUT)

Endpoints:

• PUT /api/gardens/{id}
• PUT /api/plants/{id}
• PUT /api/plantings/{id}
• PUT /api/tasks/{id}
• PUT /api/tools/{id}
• PUT /api/astuces/{id}

Envoyer un objet complet cohérent (champs requis inclus).

5.2 Statut tâche rapide

PUT /api/tasks/{id}/statut?statut=en_cours

6) Upload image/vidéo + association

6.1 Upload binaire

POST /api/upload (multipart file)

Réponse type:

{
  "url": "/uploads/abc.webp",
  "thumbnail_url": "/uploads/def.webp"
}

6.2 Attacher à une entité (bibliothèque média)

POST /api/media

{
  "entity_type": "plante",
  "entity_id": 12,
  "url": "/uploads/abc.webp",
  "thumbnail_url": "/uploads/def.webp",
  "titre": "Tomate serre mai 2026"
}

entity_type autorisés:

• jardin
• plante
• adventice
• outil
• plantation
• bibliotheque

7) Ajouter des liens URL (utile pour notices/sources)

Utiliser la table attachments via API.

7.1 Créer une pièce jointe URL

POST /api/attachments

{
  "entity_type": "plante",
  "entity_id": 12,
  "type": "url",
  "titre": "Fiche technique tomate",
  "contenu": "https://example.org/fiche-tomate"
}

7.2 Lire les liens d'une entité

GET /api/attachments?entity_type=plante&entity_id=12

8) Gabarit OpenClaw (HTTP action)

Utiliser ce format logique dans les étapes OpenClaw:

{
  "name": "create_plant",
  "method": "POST",
  "url": "http://192.168.1.50:8060/api/plants",
  "headers": {
    "Content-Type": "application/json"
  },
  "json": {
    "nom_commun": "Tomate",
    "categorie": "potager"
  },
  "expected_status": 201,
  "map_output": {
    "plant_id": "$.id"
  }
}

9) Erreurs fréquentes

• 422 Unprocessable Entity: payload incomplet ou type invalide.
• 404: ID référencé introuvable.
• 400 sur upload: mauvais content-type.
• Réseau/CORS:
  • serveur-à-serveur OpenClaw -> CORS non nécessaire
  • navigateur -> configurer CORS_ORIGINS côté backend