bouncer/doc/fr/references/admin_api.md

# API d'administration

## Authentification

L'ensemble des appels aux APIs HTTP du service `bouncer-admin` sont authentifiées via l'utilisation d'un jeton [JWT](https://datatracker.ietf.org/doc/html/rfc7519) signé par la clé privée du serveur.

Le jeton d'accès doit être transmis avec l'ensemble des appels aux points d'entrée via l'entête HTTP `Authorization` en respectant la forme suivante:

```
Authorization: Bearer <jwt>
```

### Génération d'un jeton d'authentification

La génération d'un jeton d'authentification s'effectue via la commande suivante:

```shell
bouncer auth create-token --subject "<subject>" --role "<role>"
```

Où:

- `"<subject>"` est une chaîne de caractère arbitraire ayant pour objectif d'identifier de manière unique l'utilisateur associé au jeton;
- `"<role>"` peut prendre une des deux valeurs `reader` ou `writer` correspondant aux droits suivants respectifs:
  - droit en lecture sur l'ensemble des entités (proxy, layer);
  - droit en lecture ET en écriture sur l'ensemble des entités.

## Points d'entrée

### `POST /api/v1/proxies`

Créer un nouveau proxy

#### Exemple de corps de requête

```json
{
  "name": "myproxy", // OBLIGATOIRE - Nom du proxy
  "to": "https://www.cadoles.com", // OBLIGATOIRE - Site distant ciblé par le proxy
  "from": ["*"] // OPTIONNEL - Liste de patrons de filtrage associés au proxy
}
```

#### Exemple de résultat

```json
{
  "data": {
    "proxy": {
      "name": "myproxy",
      "weight": 0,
      "enabled": false,
      "to": "https://www.cadoles.com",
      "from": ["*"],
      "createdAt": "2018-12-10T13:45:00.000Z",
      "updatedAt": "2018-12-10T13:45:00.000Z"
    }
  }
}
```

#### Source

Voir [`internal/admin/proxy_route.go#createProxy()`](../../../internal/admin/proxy_route.go#createProxy)

### `GET /api/v1/proxies/{proxyName}`

Récupérer les informations complètes sur un proxy

#### Paramètres

- `{proxyName}` - Nom du proxy

#### Exemple de résultat

```json
{
  "data": {
    "proxy": {
      "name": "myproxy",
      "weight": 0,
      "enabled": false,
      "to": "https://www.cadoles.com",
      "from": ["*"],
      "createdAt": "2018-12-10T13:45:00.000Z",
      "updatedAt": "2018-12-10T13:45:00.000Z"
    }
  }
}
```

#### Source

Voir [`internal/admin/proxy_route.go#getProxy()`](../../../internal/admin/proxy_route.go#getProxy)

### `PUT /api/v1/proxies/{proxyName}`

Modifier un proxy

#### Exemple de corps de requête

```json
{
  "to": "https://www.cadoles.com", // OPTIONNEL - Site distant ciblé par le proxy
  "from": ["mylocalproxydomain:*"], // OPTIONNEL - Liste de patrons de filtrage associés au proxy
  "weight": 100, // OPTIONNEL - Poids à associer au proxy
  "enabled": true // OPTIONNEL - Activer/désactiver le proxy
}
```

#### Exemple de résultat

```json
{
  "data": {
    "proxy": {
      "name": "myproxy",
      "weight": 100,
      "enabled": true,
      "to": "https://www.cadoles.com",
      "from": ["mylocalproxydomain:*"],
      "createdAt": "2018-12-10T13:45:00.000Z",
      "updatedAt": "2020-10-02T15:09:00.000Z"
    }
  }
}
```

#### Source

Voir [`internal/admin/proxy_route.go#updateProxy()`](../../../internal/admin/proxy_route.go#updateProxy)

### `GET /api/v1/proxies?names={name1,name2,...}`

Lister les proxies existants

#### Paramètres

- `{names}` - Optionnel - Liste des noms de proxy à appliquer en tant que filtre

#### Exemple de résultat

```json
{
  "data": {
    "proxies": [
      {
        "name": "myproxy",
        "weight": 0,
        "enabled": false
      }
    ]
  }
}
```

#### Source

Voir [`internal/admin/proxy_route.go#queryProxy()`](../../../internal/admin/proxy_route.go#queryProxy)

## `DELETE /api/v1/proxies/{proxyName}`

Supprimer le proxy

#### Paramètres

- `{proxyName}` - Nom du proxy

#### Exemple de résultat

```json
{
  "data": {
    "proxyName": "myproxy"
  }
}
```

#### Source

Voir [`internal/admin/proxy_route.go#deleteProxy()`](../../../internal/admin/proxy_route.go#deleteProxy)