# 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:

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

Réponse attendue:

```json
{"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`

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

### 4.2 Plante

`POST /api/plants`

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

### 4.3 Plantation

`POST /api/plantings`

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

### 4.4 Tâche

`POST /api/tasks`

```json
{
  "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`

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

### 4.6 Astuce

`POST /api/astuces`

```json
{
  "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:

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

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

`POST /api/media`

```json
{
  "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`

```json
{
  "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:

```json
{
  "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