[FEAT] First functional version.
This commit is contained in:
NADAL Jean-Baptiste
386
api/README.md
Normal file
386
api/README.md
Normal file
@@ -0,0 +1,386 @@
|
||||
# OHMJ API Documentation
|
||||
|
||||
API REST pour la gestion des partitions de l'Harmonie de Montpellier-Jacou.
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
http://localhost:8000
|
||||
```
|
||||
|
||||
## Authentification
|
||||
|
||||
L'API utilise JWT (JSON Web Token) pour l'authentification.
|
||||
|
||||
### Login
|
||||
|
||||
```http
|
||||
POST /login
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Corps de la requête :**
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "password"
|
||||
}
|
||||
```
|
||||
|
||||
**Réponse :**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"user": {
|
||||
"username": "admin",
|
||||
"role": "admin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Rôles disponibles :**
|
||||
- `admin` - Accès complet
|
||||
- `user` - Accès lecture seule
|
||||
|
||||
### Utilisation du token
|
||||
|
||||
Inclure le token dans l'en-tête `Authorization` :
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### GET /scores
|
||||
|
||||
Liste toutes les partitions.
|
||||
|
||||
```http
|
||||
GET /scores
|
||||
```
|
||||
|
||||
**Réponse :**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"scores": [
|
||||
{
|
||||
"id": "102",
|
||||
"name": "A Legend from Yao",
|
||||
"compositor": "Yeh Shu-Han"
|
||||
},
|
||||
{
|
||||
"id": "390",
|
||||
"name": "La part d Euterpe",
|
||||
"compositor": "Michael CUVILLON"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /scores/:id
|
||||
|
||||
Détails d'une partition. Pour les partitions multi-morceaux (ex: 390), retourne tous les instruments de toutes les pièces.
|
||||
|
||||
```http
|
||||
GET /scores/102
|
||||
GET /scores/390
|
||||
```
|
||||
|
||||
**Réponse (score simple) :**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"score": {
|
||||
"id": "102",
|
||||
"name": "A Legend from Yao",
|
||||
"compositor": "Yeh Shu-Han",
|
||||
"instruments": [
|
||||
{
|
||||
"id": "cla",
|
||||
"title": "Clarinette",
|
||||
"piece": "1",
|
||||
"parts": [
|
||||
{
|
||||
"id": "1",
|
||||
"files": [
|
||||
{
|
||||
"name": "clarinette-sib-1",
|
||||
"filename": "clarinette-sib-1.pdf",
|
||||
"path": "102/1/cla/1/clarinette-sib-1.pdf",
|
||||
"part": "1",
|
||||
"key": "sib",
|
||||
"clef": null,
|
||||
"variant": null
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Réponse (partition multi-morceaux comme 390) :**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"score": {
|
||||
"id": "390",
|
||||
"name": "La part d Euterpe",
|
||||
"compositor": "Michael CUVILLON",
|
||||
"instruments": [
|
||||
{
|
||||
"id": "cla",
|
||||
"title": "Clarinette",
|
||||
"piece": "1",
|
||||
"parts": [...]
|
||||
},
|
||||
{
|
||||
"id": "sax",
|
||||
"title": "Sax Alto",
|
||||
"piece": "2",
|
||||
"parts": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /scores/:id/instruments
|
||||
|
||||
Liste les instruments d'une partition. Pour les partitions multi-morceaux (ex: 390), peut filtrer par pièce.
|
||||
|
||||
```http
|
||||
GET /scores/102/instruments
|
||||
GET /scores/390/instruments?piece=1
|
||||
```
|
||||
|
||||
**Paramètre optionnel :**
|
||||
- `piece` - Numéro de la pièce (pour partitions multi-morceaux)
|
||||
|
||||
**Réponse :**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"instruments": [
|
||||
{
|
||||
"id": "cla",
|
||||
"title": "Clarinette",
|
||||
"piece": "1",
|
||||
"parts": [
|
||||
{
|
||||
"id": "1",
|
||||
"files": [
|
||||
{
|
||||
"name": "clarinette-sib-1",
|
||||
"filename": "clarinette-sib-1.pdf",
|
||||
"path": "102/1/cla/1/clarinette-sib-1.pdf",
|
||||
"part": "1",
|
||||
"key": "sib",
|
||||
"clef": null,
|
||||
"variant": null
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Champs des fichiers :**
|
||||
- `name` - Nom du fichier sans extension
|
||||
- `filename` - Nom du fichier avec extension
|
||||
- `path` - Chemin relatif pour download
|
||||
- `part` - Numéro de partie (ex: "1", "2_3")
|
||||
- `key` - Tonalité (ex: "sib", "mib", "fa")
|
||||
- `clef` - Clé (ex: "clesol", "clefa")
|
||||
- `variant` - Variante (ex: "solo", "default")
|
||||
|
||||
---
|
||||
|
||||
### GET /pieces/:scoreId
|
||||
|
||||
Liste les pièces d'une partition.
|
||||
|
||||
```http
|
||||
GET /pieces/102
|
||||
```
|
||||
|
||||
**Réponse :**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"pieces": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Pièce 1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /download/:path
|
||||
|
||||
Télécharge un fichier PDF.
|
||||
|
||||
```http
|
||||
GET /download/102/1/cla/1/clarinette-sib-1.pdf
|
||||
```
|
||||
|
||||
**Réponse :** Fichier PDF (Content-Type: application/pdf)
|
||||
|
||||
**Structure des chemins :**
|
||||
```
|
||||
NUM/PIECE/INSTRUMENT/VERSION/PARTIE.pdf
|
||||
```
|
||||
|
||||
**Instruments disponibles :**
|
||||
| Code | Instrument |
|
||||
|------|------------|
|
||||
| dir | Direction |
|
||||
| pic | Piccolo |
|
||||
| flu | Flûte |
|
||||
| cla | Clarinette |
|
||||
| clb | Clarinette basse |
|
||||
| sax | Saxophone alto |
|
||||
| sab | Saxophone baryton |
|
||||
| sat | Saxophone ténor |
|
||||
| cba | Contrebasse |
|
||||
| cor | Cor |
|
||||
| trp | Trompette |
|
||||
| trb | Trombone |
|
||||
| tub | Tuba |
|
||||
| htb | Hautbois |
|
||||
| bas | Basson |
|
||||
| per | Percussion |
|
||||
| crn | Cornet |
|
||||
| eup | Euphonium |
|
||||
|
||||
---
|
||||
|
||||
## Routes Admin
|
||||
|
||||
### POST /admin/scores
|
||||
|
||||
Créer une nouvelle partition.
|
||||
|
||||
```http
|
||||
POST /admin/scores
|
||||
Authorization: Bearer <token_admin>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Corps de la requête :**
|
||||
```json
|
||||
{
|
||||
"id": "200",
|
||||
"name": "Nouvelle partition",
|
||||
"compositor": "Compositeur"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### PUT /admin/scores/:id
|
||||
|
||||
Mettre à jour une partition.
|
||||
|
||||
```http
|
||||
PUT /admin/scores/102
|
||||
Authorization: Bearer <token_admin>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Corps de la requête :**
|
||||
```json
|
||||
{
|
||||
"name": "Nouveau nom",
|
||||
"compositor": "Nouveau compositeur"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### DELETE /admin/scores/:id
|
||||
|
||||
Supprimer une partition.
|
||||
|
||||
```http
|
||||
DELETE /admin/scores/102
|
||||
Authorization: Bearer <token_admin>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /admin/upload
|
||||
|
||||
Uploader un fichier PDF.
|
||||
|
||||
```http
|
||||
POST /admin/upload
|
||||
Authorization: Bearer <token_admin>
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
**Corps de la requête :**
|
||||
```
|
||||
file: <fichier_pdf>
|
||||
scoreId: 102
|
||||
pieceId: 1
|
||||
instrument: cla
|
||||
version: 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Codes d'erreur
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 200 | Succès |
|
||||
| 401 | Non authentifié |
|
||||
| 403 | Accès interdit (rôle insufficient) |
|
||||
| 404 | Ressource non trouvée |
|
||||
| 500 | Erreur serveur |
|
||||
|
||||
---
|
||||
|
||||
## Lancer le serveur
|
||||
|
||||
```bash
|
||||
cd api
|
||||
php -S localhost:8000 router.php
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Structure des fichiers
|
||||
|
||||
```
|
||||
legacy/Scores/
|
||||
├── 102/
|
||||
│ ├── 1/
|
||||
│ │ ├── cla/
|
||||
│ │ │ ├── 1/
|
||||
│ │ │ │ ├── clarinette-sib-1.pdf
|
||||
│ │ │ │ ├── clarinette-sib-2.pdf
|
||||
│ │ │ │ └── clarinette-mib-1.pdf
|
||||
│ │ │ └── 2/
|
||||
│ │ │ └── clarinette-sib-1.pdf
|
||||
│ │ ├── flu/
|
||||
│ │ └── sax/
|
||||
│ └── 2/
|
||||
└── score.ini
|
||||
```
|
||||
Reference in New Issue
Block a user