> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wethehivers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections API

> Exports Postman, Insomnia et Bruno prêts à l'emploi

# Collections API

Toutes les collections couvrent les **172 endpoints** de l'API, groupés par module. Maintenues automatiquement à partir de `openapi.json`.

## Téléchargements

| Outil    | Fichier                                                               | Format  |
| -------- | --------------------------------------------------------------------- | ------- |
| Postman  | [`thehive-api.postman.json`](/collections/thehive-api.postman.json)   | v2.1    |
| Insomnia | [`thehive-api.insomnia.json`](/collections/thehive-api.insomnia.json) | v4      |
| Bruno    | [`collections/bruno/`](/collections/bruno/)                           | Dossier |
| OpenAPI  | [`openapi.json`](/api-reference/openapi.json)                         | 3.0     |

## Variables d'environnement

Les collections utilisent ces variables — à configurer dans votre outil :

| Variable        | Prod                                 | Staging                                      | Dev                            |
| --------------- | ------------------------------------ | -------------------------------------------- | ------------------------------ |
| `base_url`      | `https://api.wethehivers.com/v1/api` | `https://staging-api.wethehivers.com/v1/api` | `http://localhost:3091/v1/api` |
| `access_token`  | `(login)`                            | `(login)`                                    | `(login)`                      |
| `refresh_token` | `(login)`                            | `(login)`                                    | `(login)`                      |

## Flow d'utilisation

```mermaid theme={null}
flowchart LR
    DL[Télécharger collection] --> IMP[Import dans l'outil]
    IMP --> ENV[Configurer base_url]
    ENV --> AUTH[Exécuter login]
    AUTH --> STORE[Token stocké auto]
    STORE --> CALL[Appeler endpoints]
```

## 1. Postman

### Import

```bash theme={null}
# Via CLI Newman (optionnel)
newman run thehive-api.postman.json \
  --env-var base_url=https://api.wethehivers.com/v1/api \
  --env-var access_token=<TOKEN>
```

### Ou via l'UI

1. **File → Import → Upload Files**
2. Sélectionner `thehive-api.postman.json`
3. Créer un environnement avec les variables ci-dessus
4. Lancer `Auth / login` → tokens stockés automatiquement

### Script de test auto (login)

Au niveau de la collection, dans **Tests** :

```javascript theme={null}
if (pm.response.code === 200 && pm.info.requestName === 'login') {
  const data = pm.response.json();
  pm.environment.set('access_token', data.accessToken);
  pm.environment.set('refresh_token', data.refreshToken);
}
```

## 2. Insomnia

```mermaid theme={null}
flowchart TD
    DL[Download .insomnia.json] --> OPEN[Insomnia]
    OPEN --> IMP[Application → Import Data → From File]
    IMP --> ENV[Manage Environments]
    ENV --> VAR[Ajouter base_url + tokens]
    VAR --> RUN[Exécuter]
```

Variables dans **Environment** (JSON) :

```json theme={null}
{
  "base_url": "https://api.wethehivers.com/v1/api",
  "access_token": "",
  "refresh_token": ""
}
```

## 3. Bruno

Bruno stocke les collections comme des fichiers `.bru` en markdown — versionnable avec git.

```bash theme={null}
# Cloner la doc et ouvrir le dossier
git clone https://gitlab.com/the-hive5354847/docs.git
cd docs/collections/bruno
# Ouvrir avec l'app Bruno → Open Collection → choisir ce dossier
```

### Structure

```
collections/bruno/
├── bruno.json              # méta collection
├── environments/
│   ├── Production.bru      # base_url prod
│   ├── Staging.bru         # base_url staging
│   └── Dev.bru             # base_url localhost
├── auth/
│   ├── login.bru
│   ├── logout.bru
│   └── refresh-token.bru
├── candidats/
│   ├── register.bru
│   └── profile.bru
...
```

### Exemple `login.bru`

```
meta {
  name: login
  type: http
  seq: 1
}
post {
  url: {{base_url}}/auth/login
  body: json
  auth: none
}
body:json {
  {
    "email": "test@example.com",
    "password": "Passw0rd!"
  }
}
script:post-response {
  bru.setEnvVar("access_token", res.body.accessToken);
  bru.setEnvVar("refresh_token", res.body.refreshToken);
}
```

## 4. Régénération

Les collections sont générées depuis `api-reference/openapi.json`. Pour régénérer localement :

```bash theme={null}
# Postman (via openapi-to-postmanv2)
npx openapi-to-postmanv2 \
  -s api-reference/openapi.json \
  -o collections/thehive-api.postman.json

# Insomnia (via openapi-to-insomnia)
npx openapi-to-insomnia \
  api-reference/openapi.json > collections/thehive-api.insomnia.json

# Bruno (via bruno-converters)
bruno generate \
  --from openapi \
  --input api-reference/openapi.json \
  --output collections/bruno/
```

## 5. Exemples d'appels pré-configurés

Toutes les requêtes incluent :

* **Headers** : `Authorization: Bearer {{access_token}}`, `Content-Type: application/json`
* **Exemples de body** avec valeurs fictives cohérentes
* **Paramètres de chemin** pré-remplis (`:id = 1`)
* **Tests automatiques** de base (status 2xx, schéma JSON)

## 6. Workflow CI

```mermaid theme={null}
flowchart LR
    DEV[Dev push spec] --> GEN[CI regen collections]
    GEN --> COM[Commit dans docs repo]
    COM --> PUB[Publier sur Mintlify]
    PUB --> DL[Utilisateurs téléchargent]
```

Les collections sont régénérées automatiquement à chaque modification du backend Spring Boot (trigger GitLab CI `docs:regenerate-collections`).

## Voir aussi

* [Authentification](/authentication)
* [OpenAPI spec](/api-reference/openapi.json)
* [Snippets JS](/dx/snippets-js), [Java](/dx/snippets-java), [Python](/dx/snippets-python)