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

```json5
{
  "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

```json5
{
    "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

```json5
{
    "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

```json5
{
  "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

```json5
{
    "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

```json5
{
    "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

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

#### Source

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