API REST v1

Référence des endpoints publics de l'API gitrust v1. Pour tester interactivement, accède à l'interface Swagger de ton instance sur /api/docs.

Authentification

L'API accepte deux méthodes d'authentification :

JWT Bearer (session web)

Obtenu via POST /api/v1/auth/login. Durée de vie courte, renouvelable via /api/v1/auth/refresh.

Authorization: Bearer <jwt_token>

Personal Access Token (PAT)

Créé dans /settings/tokens. Durée de vie configurable, révocable à tout moment.

Authorization: Bearer gr_pat_xxxx...

Les deux méthodes utilisent le même header Authorization: Bearer. gitrust détecte automatiquement le type par le préfixe du token.

Pagination

Tous les endpoints de liste supportent la pagination par curseur de page :

Paramètre Type Défaut Description
page int 1 Numéro de page (commence à 1)
limit int 20 Résultats par page (max 100)

Exemple :

GET /api/v1/repos/owner/repo/issues?page=2&limit=50

Les réponses paginées incluent les headers :

X-Total-Count: 142
X-Page: 2
X-Per-Page: 50

Codes de réponse

Code Signification
200 OK Succès
201 Created Ressource créée
204 No Content Succès sans corps de réponse
400 Bad Request Paramètres invalides
401 Unauthorized Token absent ou expiré
403 Forbidden Authentifié mais permissions insuffisantes
404 Not Found Ressource introuvable ou non accessible
422 Unprocessable Entity Validation échouée (corps JSON avec détails)
429 Too Many Requests Rate limit atteint

Les erreurs retournent un corps JSON :

{
  "error": "repository not found",
  "code": "REPO_NOT_FOUND"
}

Endpoints — Authentification

Méthode Endpoint Description
POST /api/v1/auth/login Connexion email + password (+ code 2FA si activé)
POST /api/v1/auth/register Créer un compte
POST /api/v1/auth/refresh Renouveler le JWT
POST /api/v1/auth/logout Invalider la session
GET /api/v1/auth/me Infos de l'utilisateur connecté (alias de /api/v1/user)
POST /api/v1/auth/forgot-password Envoyer le lien de réinitialisation
POST /api/v1/auth/reset-password Changer le mot de passe via token email
POST /api/v1/auth/2fa/verify Vérifier le code TOTP lors de la connexion

Endpoints — Utilisateur

Méthode Endpoint Description
GET /api/v1/user Profil de l'utilisateur authentifié
GET /api/v1/user/repos Dépôts accessibles par l'utilisateur authentifié

Exemple de réponse GET /api/v1/user :

{
  "id": 42,
  "username": "tonpseudo",
  "email": "ton@email.com",
  "avatar_url": "https://gitrust.example.com/avatars/42.png",
  "created_at": "2026-01-15T10:30:00Z"
}

Endpoints — Dépôts

Méthode Endpoint Description
GET /api/v1/repos/{owner}/{repo} Détail d'un dépôt
GET /api/v1/repos/{owner}/{repo}/branches Liste des branches
GET /api/v1/repos/{owner}/{repo}/tags Liste des tags
GET /api/v1/repos/{owner}/{repo}/commits Liste des commits (paginée)

Exemple de réponse GET /api/v1/repos/owner/repo :

{
  "id": 7,
  "owner": "owner",
  "name": "repo",
  "full_name": "owner/repo",
  "description": "Mon dépôt",
  "private": false,
  "default_branch": "main",
  "stars_count": 3,
  "forks_count": 0,
  "created_at": "2026-02-01T09:00:00Z",
  "updated_at": "2026-04-15T14:22:00Z"
}

Endpoints — Issues

Méthode Endpoint Description
GET /api/v1/repos/{owner}/{repo}/issues Lister les issues (filtres : state, labels, page, limit)
POST /api/v1/repos/{owner}/{repo}/issues Créer une issue
GET /api/v1/repos/{owner}/{repo}/issues/{num} Détail d'une issue
PATCH /api/v1/repos/{owner}/{repo}/issues/{num} Modifier une issue
POST /api/v1/repos/{owner}/{repo}/issues/{num}/comments Ajouter un commentaire

Exemple POST /api/v1/repos/owner/repo/issues :

{
  "title": "Bug: validation email incorrecte",
  "body": "La validation rejette les adresses avec un + dans le local-part."
}

Endpoints — Pull Requests

Méthode Endpoint Description
GET /api/v1/repos/{owner}/{repo}/pulls Lister les PRs
POST /api/v1/repos/{owner}/{repo}/pulls Créer une PR
GET /api/v1/repos/{owner}/{repo}/pulls/{num} Détail d'une PR
POST /api/v1/repos/{owner}/{repo}/pulls/{num}/merge Fusionner une PR
POST /api/v1/repos/{owner}/{repo}/pulls/{num}/comments Commenter une PR

Exemple POST /api/v1/repos/owner/repo/pulls/{num}/merge :

{
  "merge_method": "squash",
  "commit_title": "feat: améliore la validation email (#5)"
}

Valeurs merge_method : merge (merge commit), squash, rebase (fast-forward).

Endpoints — CI

Méthode Endpoint Description
GET /api/v1/repos/{owner}/{repo}/ci/pipelines Lister les pipelines
POST /api/v1/repos/{owner}/{repo}/ci/pipelines/trigger Déclencher un pipeline manuellement
GET /api/v1/repos/{owner}/{repo}/ci/pipelines/{id} Détail d'un pipeline
GET /api/v1/repos/{owner}/{repo}/ci/pipelines/{id}/logs Logs d'un pipeline
GET /api/v1/repos/{owner}/{repo}/ci/config Lire la config CI
PUT /api/v1/repos/{owner}/{repo}/ci/config Mettre à jour la config CI
GET /api/v1/repos/{owner}/{repo}/ci/variables Lister les variables CI
POST /api/v1/repos/{owner}/{repo}/ci/variables Créer une variable CI
DELETE /api/v1/repos/{owner}/{repo}/ci/variables/{id} Supprimer une variable CI

Documentation interactive

L'interface Swagger complète est disponible sur ton instance à /api/docs. Elle permet de tester chaque endpoint directement depuis le navigateur avec ton token d'authentification.

La spécification OpenAPI brute (YAML) est disponible sur /api/docs/openapi.yaml.

Voir aussi