Change d'interface plus légére, modification side barre
This commit is contained in:
377
API.md
377
API.md
@ -6,6 +6,7 @@ Base URL: `http://localhost:8080/api/v1`
|
||||
## Table des matières
|
||||
|
||||
- [Vue d'ensemble](#vue-densemble)
|
||||
- [Commandes CLI](#commandes-cli)
|
||||
- [Authentification](#authentification)
|
||||
- [Formats de données](#formats-de-données)
|
||||
- [Endpoints](#endpoints)
|
||||
@ -13,6 +14,9 @@ Base URL: `http://localhost:8080/api/v1`
|
||||
- [Récupérer une note](#récupérer-une-note)
|
||||
- [Créer/Mettre à jour une note](#créermettre-à-jour-une-note)
|
||||
- [Supprimer une note](#supprimer-une-note)
|
||||
- [Lister les notes publiques](#lister-les-notes-publiques)
|
||||
- [Basculer le statut public d'une note](#basculer-le-statut-public-dune-note)
|
||||
- [Notes publiques](#notes-publiques)
|
||||
- [Codes de statut HTTP](#codes-de-statut-http)
|
||||
- [Exemples d'utilisation](#exemples-dutilisation)
|
||||
|
||||
@ -38,6 +42,69 @@ L'API REST de PersoNotes permet de gérer vos notes Markdown via HTTP. Elle supp
|
||||
|
||||
---
|
||||
|
||||
## Commandes CLI
|
||||
|
||||
Le serveur inclut des commandes CLI intégrées pour gérer les notes publiques sans avoir à lancer le serveur HTTP.
|
||||
|
||||
### Lister les notes publiques
|
||||
|
||||
Affiche toutes les notes qui ont été exportées en HTML public.
|
||||
|
||||
**Commande** :
|
||||
```bash
|
||||
./server list-public [notes-dir]
|
||||
```
|
||||
|
||||
**Arguments** :
|
||||
- `notes-dir` (optionnel) : Chemin vers le répertoire des notes (défaut: `./notes`)
|
||||
|
||||
**Exemple de sortie** :
|
||||
```
|
||||
📚 Notes publiques (4):
|
||||
|
||||
• 2025 Learning Goals
|
||||
Source: personal/learning-goals.md
|
||||
Public: public/learning-goals.html
|
||||
Date: 2025-11-13 20:06:21
|
||||
|
||||
• AI Writing Assistant
|
||||
Source: archive/ai-assistant.md
|
||||
Public: public/ai-assistant.html
|
||||
Date: 2025-11-13 19:43:28
|
||||
|
||||
• API Endpoints Reference
|
||||
Source: documentation/api/endpoints.md
|
||||
Public: public/endpoints.html
|
||||
Date: 2025-11-13 19:36:57
|
||||
|
||||
• Product Backlog
|
||||
Source: tasks/backlog.md
|
||||
Public: public/backlog.html
|
||||
Date: 2025-11-13 20:13:05
|
||||
```
|
||||
|
||||
**Cas particuliers** :
|
||||
- Si aucune note n'est publique : affiche "Aucune note publique."
|
||||
- Si le fichier `.public.json` n'existe pas : affiche "Aucune note publique trouvée."
|
||||
- Erreur si le répertoire n'existe pas
|
||||
|
||||
**Utilisation typique** :
|
||||
```bash
|
||||
# Lister les notes publiques
|
||||
./server list-public
|
||||
|
||||
# Avec un répertoire personnalisé
|
||||
./server list-public /path/to/notes
|
||||
|
||||
# Compter les notes publiques (Linux/macOS)
|
||||
./server list-public | grep -c "^•"
|
||||
|
||||
# Exporter la liste dans un fichier
|
||||
./server list-public > public-notes-list.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Authentification
|
||||
|
||||
**Version actuelle : Aucune authentification requise**
|
||||
@ -364,6 +431,313 @@ curl -X DELETE http://localhost:8080/api/v1/notes/projet/old-note.md
|
||||
|
||||
---
|
||||
|
||||
### Lister les notes publiques
|
||||
|
||||
Récupère la liste des notes qui ont été publiées dans l'espace public.
|
||||
|
||||
**Endpoint** : `GET /api/public/list`
|
||||
|
||||
**Paramètres** : Aucun
|
||||
|
||||
**Réponse** : `200 OK`
|
||||
|
||||
```json
|
||||
{
|
||||
"notes": [
|
||||
{
|
||||
"path": "projet/backend.md",
|
||||
"title": "Backend API",
|
||||
"published_at": "2025-11-13T14:30:00Z"
|
||||
},
|
||||
{
|
||||
"path": "personal/guide.md",
|
||||
"title": "Guide d'utilisation",
|
||||
"published_at": "2025-11-13T10:15:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Champs retournés** :
|
||||
- `path` : Chemin relatif de la note source
|
||||
- `title` : Titre de la note
|
||||
- `published_at` : Date/heure de publication (format ISO 8601)
|
||||
|
||||
**Notes** :
|
||||
- Les notes sont triées par date de publication (plus récentes d'abord)
|
||||
- Les fichiers HTML générés se trouvent dans `public/{nom-de-la-note}.html`
|
||||
- Liste vide si aucune note n'est publique
|
||||
|
||||
**Exemple curl** :
|
||||
|
||||
```bash
|
||||
# Lister toutes les notes publiques
|
||||
curl http://localhost:8080/api/public/list
|
||||
|
||||
# Avec formatage jq
|
||||
curl -s http://localhost:8080/api/public/list | jq '.notes[] | "\(.title) -> public/\(.path | split("/")[-1] | sub(".md$"; ".html"))"'
|
||||
```
|
||||
|
||||
**Exemple de sortie formatée** :
|
||||
|
||||
```bash
|
||||
$ curl -s http://localhost:8080/api/public/list | jq '.notes[] | .title'
|
||||
"Backend API"
|
||||
"Guide d'utilisation"
|
||||
"Documentation projet"
|
||||
```
|
||||
|
||||
**Compter les notes publiques** :
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8080/api/public/list | jq '.notes | length'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Basculer le statut public d'une note
|
||||
|
||||
Publie ou retire une note de l'espace public. Génère automatiquement un fichier HTML statique exportable.
|
||||
|
||||
**Endpoint** : `POST /api/public/toggle`
|
||||
|
||||
**Content-Type** : `application/x-www-form-urlencoded`
|
||||
|
||||
**Paramètres** :
|
||||
- `path` (form) : Chemin relatif de la note (ex: `projet/backend.md`)
|
||||
|
||||
**Réponse** : `200 OK`
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "public",
|
||||
"path": "projet/backend.md"
|
||||
}
|
||||
```
|
||||
|
||||
Valeurs possibles pour `status` :
|
||||
- `"public"` : La note est maintenant publique (HTML généré)
|
||||
- `"private"` : La note est maintenant privée (HTML supprimé)
|
||||
|
||||
**Comportement** :
|
||||
- ✅ **Génère du HTML statique** dans `public/nom-de-la-note.html`
|
||||
- ✅ **Copie les CSS** nécessaires dans `public/static/`
|
||||
- ✅ **Met à jour l'index** dans `public/index.html`
|
||||
- ✅ **Structure plate** : Tous les fichiers dans `public/`, pas de sous-dossiers
|
||||
- ✅ **Portable** : Les fichiers HTML peuvent être copiés sur n'importe quel serveur web
|
||||
|
||||
**Fichiers générés** :
|
||||
```
|
||||
public/
|
||||
├── index.html # Liste de toutes les notes publiques
|
||||
├── backend.md.html # Note convertie en HTML standalone
|
||||
├── autre-note.html
|
||||
└── static/
|
||||
├── theme.css # Styles copiés
|
||||
└── themes.css
|
||||
```
|
||||
|
||||
**Erreurs** :
|
||||
- `400 Bad Request` : Chemin manquant ou invalide
|
||||
- `404 Not Found` : Note inexistante
|
||||
- `405 Method Not Allowed` : Méthode autre que POST
|
||||
- `500 Internal Server Error` : Erreur de génération HTML
|
||||
|
||||
**Exemple curl** :
|
||||
|
||||
```bash
|
||||
# Publier une note
|
||||
curl -X POST http://localhost:8080/api/public/toggle \
|
||||
-d "path=projet/backend.md"
|
||||
|
||||
# La note est maintenant accessible à :
|
||||
# http://localhost:8080/public/backend.html
|
||||
```
|
||||
|
||||
**Exemple JavaScript** :
|
||||
|
||||
```javascript
|
||||
// Publier une note
|
||||
const response = await fetch('/api/public/toggle', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/x-www-form-urlencoded',
|
||||
},
|
||||
body: new URLSearchParams({ path: 'projet/backend.md' }),
|
||||
});
|
||||
|
||||
const data = await response.json();
|
||||
console.log(data.status); // "public" ou "private"
|
||||
```
|
||||
|
||||
**Scripts utiles** :
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Lister les notes publiques avec leurs URLs
|
||||
|
||||
echo "📚 Notes publiques:"
|
||||
curl -s http://localhost:8080/api/public/list | jq -r '.notes[] | "• \(.title)\n → http://localhost:8080/public/\(.path | split("/")[-1] | sub(".md$"; ".html"))\n"'
|
||||
```
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Exporter toutes les notes en HTML public
|
||||
|
||||
echo "Exporting all notes to public HTML..."
|
||||
curl -s http://localhost:8080/api/v1/notes | jq -r '.notes[].path' | while read path; do
|
||||
curl -X POST http://localhost:8080/api/public/toggle -d "path=$path" > /dev/null 2>&1
|
||||
echo "✓ Published: $path"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "✅ Export terminé!"
|
||||
echo "📊 Total: $(curl -s http://localhost:8080/api/public/list | jq '.notes | length') notes publiques"
|
||||
```
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Retirer toutes les notes du public
|
||||
|
||||
echo "Unpublishing all public notes..."
|
||||
curl -s http://localhost:8080/api/public/list | jq -r '.notes[].path' | while read path; do
|
||||
curl -X POST http://localhost:8080/api/public/toggle -d "path=$path" > /dev/null 2>&1
|
||||
echo "✓ Unpublished: $path"
|
||||
done
|
||||
|
||||
echo "✅ Toutes les notes sont maintenant privées"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes publiques
|
||||
|
||||
Le système de notes publiques génère des fichiers HTML statiques exportables. Cette section explique comment utiliser ces fichiers.
|
||||
|
||||
### Accès aux notes publiques
|
||||
|
||||
**Sur le serveur Personotes** :
|
||||
```
|
||||
http://localhost:8080/public/
|
||||
```
|
||||
|
||||
**Fichiers générés** :
|
||||
- `public/index.html` : Liste de toutes les notes publiques
|
||||
- `public/*.html` : Notes converties en HTML standalone
|
||||
- `public/static/` : CSS et assets
|
||||
|
||||
### Déploiement
|
||||
|
||||
Les fichiers HTML sont complètement autonomes et peuvent être déployés sur :
|
||||
|
||||
#### 1. Serveur web classique
|
||||
|
||||
```bash
|
||||
# Copier sur un serveur Apache/Nginx
|
||||
scp -r public/ user@server.com:/var/www/html/notes/
|
||||
|
||||
# Ou avec rsync
|
||||
rsync -av public/ user@server.com:/var/www/html/notes/
|
||||
```
|
||||
|
||||
**Configuration Nginx** :
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name notes.example.com;
|
||||
root /var/www/html/notes;
|
||||
index index.html;
|
||||
}
|
||||
```
|
||||
|
||||
**Configuration Apache** :
|
||||
```apache
|
||||
<VirtualHost *:80>
|
||||
ServerName notes.example.com
|
||||
DocumentRoot /var/www/html/notes
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
#### 2. GitHub Pages (gratuit)
|
||||
|
||||
```bash
|
||||
cd public/
|
||||
git init
|
||||
git add .
|
||||
git commit -m "Public notes"
|
||||
git remote add origin https://github.com/username/notes-public.git
|
||||
git push -u origin main
|
||||
|
||||
# Activer GitHub Pages dans Settings → Pages → main branch
|
||||
# Vos notes seront accessibles à :
|
||||
# https://username.github.io/notes-public/
|
||||
```
|
||||
|
||||
#### 3. Netlify Drop
|
||||
|
||||
1. Allez sur https://app.netlify.com/drop
|
||||
2. Glissez-déposez le dossier `public/`
|
||||
3. Netlify génère automatiquement une URL
|
||||
|
||||
#### 4. Vercel
|
||||
|
||||
```bash
|
||||
cd public/
|
||||
npx vercel
|
||||
```
|
||||
|
||||
### Automatisation de l'export
|
||||
|
||||
**Script de synchronisation** :
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# sync-public.sh - Synchroniser les notes publiques vers un serveur
|
||||
|
||||
REMOTE_USER="user"
|
||||
REMOTE_HOST="server.com"
|
||||
REMOTE_PATH="/var/www/html/notes"
|
||||
|
||||
rsync -av --delete public/ ${REMOTE_USER}@${REMOTE_HOST}:${REMOTE_PATH}
|
||||
|
||||
echo "✅ Notes publiques synchronisées !"
|
||||
```
|
||||
|
||||
**Git Hook automatique** :
|
||||
|
||||
```bash
|
||||
# .git/hooks/post-commit
|
||||
#!/bin/bash
|
||||
|
||||
# Si le dossier public/ a changé, synchroniser
|
||||
if git diff --name-only HEAD~1 | grep -q "^public/"; then
|
||||
./sync-public.sh
|
||||
fi
|
||||
```
|
||||
|
||||
### Avantages
|
||||
|
||||
- ✅ **Performance** : HTML pré-généré = chargement instantané
|
||||
- ✅ **Sécurité** : Fichiers statiques = surface d'attaque minimale
|
||||
- ✅ **Portabilité** : Fonctionne sur n'importe quel serveur web
|
||||
- ✅ **Gratuit** : Hébergement possible sur GitHub Pages, Netlify
|
||||
- ✅ **SEO** : HTML pré-rendu = indexation optimale par Google
|
||||
- ✅ **Pas de backend** : Pas besoin de Go sur le serveur de destination
|
||||
|
||||
### Limitations
|
||||
|
||||
- ⚠️ **Noms uniques** : Si deux notes dans différents dossiers ont le même nom (ex: `personal/test.md` et `work/test.md`), elles s'écraseront car la structure est plate
|
||||
- ⚠️ **Republication manuelle** : Si vous modifiez une note déjà publique, vous devez la republier pour régénérer le HTML
|
||||
- ⚠️ **Pas de recherche** : Les fichiers HTML n'incluent pas de fonction de recherche (uniquement consultables)
|
||||
|
||||
### Documentation complète
|
||||
|
||||
Pour plus d'informations sur l'export des notes publiques :
|
||||
- **QUICK_START_PUBLIC.md** : Guide de démarrage rapide
|
||||
- **EXPORT_GUIDE.md** : Guide complet de déploiement
|
||||
|
||||
---
|
||||
|
||||
## Codes de statut HTTP
|
||||
|
||||
| Code | Signification | Description |
|
||||
@ -556,13 +930,14 @@ echo "$STATS" | jq -r '.notes[].tags[]' | sort | uniq -c | sort -rn | head -5
|
||||
|
||||
## Changelog
|
||||
|
||||
### v1 (2025-11-10)
|
||||
### v1 (2025-11-13)
|
||||
- ✨ Première version de l'API REST
|
||||
- ✅ Endpoints: LIST, GET, PUT, DELETE
|
||||
- ✅ Content negotiation JSON/Markdown
|
||||
- ✅ Support sous-dossiers
|
||||
- ✅ Gestion automatique du front matter
|
||||
- ✅ Ré-indexation automatique
|
||||
- ✅ Export de notes publiques en HTML statique (POST /api/public/toggle)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user