226 lines
3.9 KiB
Markdown
226 lines
3.9 KiB
Markdown
# 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
|
|
|