# Procédure – Utilisation de l'API Gitea

## 1. Contexte

- **Instance** : https://git.ptits-pas.fr  
- **API de base** : `https://git.ptits-pas.fr/api/v1`  
- **Projet P'titsPas** : dépôt `jmartin/petitspas` (owner = `jmartin`, repo = `petitspas`)

## 2. Authentification

### 2.1 Token

Le token est défini dans l'environnement (ex. `~/.bashrc`) :

```bash
export GITEA_TOKEN="<votre_token>"
```

Pour l'utiliser dans les commandes :

```bash
source ~/.bashrc   # ou : . ~/.bashrc
# Puis utiliser $GITEA_TOKEN dans les curl
```

### 2.2 En-tête HTTP

Toutes les requêtes API doivent envoyer le token :

```bash
-H "Authorization: token $GITEA_TOKEN"
```

Exemple :

```bash
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas"
```

## 3. Endpoints utiles

### 3.1 Dépôt (repository)

| Action        | Méthode | URL |
|---------------|---------|-----|
| Infos dépôt   | GET     | `/repos/{owner}/{repo}` |
| Liste dépôts | GET     | `/repos/search?q=petitspas` |

Exemple – infos du dépôt :

```bash
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas" | jq .
```

### 3.2 Issues (tickets)

| Action           | Méthode | URL |
|------------------|---------|-----|
| Liste des issues | GET     | `/repos/{owner}/{repo}/issues` |
| Détail d'une issue | GET   | `/repos/{owner}/{repo}/issues/{index}` |
| Créer une issue | POST    | `/repos/{owner}/{repo}/issues` |
| Modifier une issue | PATCH | `/repos/{owner}/{repo}/issues/{index}` |
| Fermer une issue | PATCH   | (même URL, `state: "closed"`) |

**Paramètres GET utiles pour la liste :**

- `state` : `open` ou `closed`
- `labels` : filtre par label (ex. `frontend`)
- `page`, `limit` : pagination

Exemples :

```bash
# Toutes les issues ouvertes
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues?state=open" | jq .

# Issues ouvertes avec label "frontend"
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues?state=open" | \
  jq '.[] | select(.labels[].name == "frontend") | {number, title, state}'

# Détail de l'issue #47
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues/47" | jq .

# Fermer l'issue #31
curl -s -X PATCH -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state":"closed"}' \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues/31"

# Créer une issue
curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Titre du ticket","body":"Description","labels":[1]}' \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues"
```

### 3.3 Pull requests

| Action        | Méthode | URL |
|---------------|---------|-----|
| Liste des PR  | GET     | `/repos/{owner}/{repo}/pulls` |
| Détail d'une PR | GET   | `/repos/{owner}/{repo}/pulls/{index}` |
| Créer une PR  | POST    | `/repos/{owner}/{repo}/pulls` |
| Fusionner une PR | POST  | `/repos/{owner}/{repo}/pulls/{index}/merge` |

Exemples :

```bash
# Liste des PR ouvertes
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/pulls?state=open" | jq .

# Créer une PR (head = branche source, base = branche cible)
curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"head":"develop","base":"master","title":"Titre de la PR"}' \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/pulls"
```

### 3.4 Branches

| Action        | Méthode | URL |
|---------------|---------|-----|
| Liste des branches | GET | `/repos/{owner}/{repo}/branches` |

```bash
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/branches" | jq '.[].name'
```

### 3.5 Webhooks

| Action        | Méthode | URL |
|---------------|---------|-----|
| Liste webhooks | GET  | `/repos/{owner}/{repo}/hooks` |
| Créer webhook | POST  | `/repos/{owner}/{repo}/hooks` |

### 3.6 Labels

| Action        | Méthode | URL |
|---------------|---------|-----|
| Liste des labels | GET | `/repos/{owner}/{repo}/labels` |

```bash
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/labels" | jq '.[] | {id, name}'
```

## 4. Résumé des URLs pour P'titsPas

Remplacer `{owner}` par `jmartin` et `{repo}` par `petitspas` :

| Ressource        | URL |
|------------------|-----|
| Dépôt            | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas` |
| Issues           | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues` |
| Issue #n         | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/issues/{n}` |
| Pull requests    | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/pulls` |
| Branches         | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/branches` |
| Labels           | `https://git.ptits-pas.fr/api/v1/repos/jmartin/petitspas/labels` |

## 5. Documentation officielle

- Swagger / OpenAPI : https://docs.gitea.com/api  
- Référence selon la version de Gitea installée (ex. 1.21, 1.25).

## 6. Dépannage

- **401 Unauthorized** : vérifier le token et l'en-tête `Authorization: token <TOKEN>`.
- **404** : vérifier owner/repo et l'URL (sensible à la casse).
- **422 / body invalide** : pour POST/PATCH, envoyer `Content-Type: application/json` et un JSON valide.