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,
        "createdAt": "2018-12-10T13:45:00.000Z",
        "updatedAt": "2018-12-10T13:45:00.000Z"
      }
    ]
  }
}
```

#### 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)

### `POST /api/v1/proxies/{proxyName}/layers`

Créer un nouveau layer pour un proxy donné

#### Paramètres

- `{proxyName}` - Nom du proxy sur lequel créer le layer

#### Exemple de corps de requête

```json
{
  "name": "mylayer", // OBLIGATOIRE - Nom du layer
  "type": "<layer_type>", // OBLIGATOIRE - Type du layer, voir doc/fr/references/layers
  "options": {} // OPTIONNEL - Options associées au layer, voir doc/fr/references/layers
}
```

#### Exemple de résultat

```json
{
  "data": {
    "layer": {
      "name": "mylayer",
      "type": "<layer_type>",
      "enabled": false,
      "weight": 0,
      "options": {},
      "createdAt": "2018-12-10T13:45:00.000Z",
      "updatedAt": "2018-12-10T13:45:00.000Z"
    }
  }
}
```

#### Source

Voir [`internal/admin/layer_route.go#createLayer()`](../../../internal/admin/layer_route.go#createLayer)

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

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

#### Paramètres

- `{proxyName}` - Nom du proxy parent
- `{layerName}` - Nom du layer

#### Exemple de résultat

```json
{
  "data": {
    "layer": {
      "name": "mylayer",
      "type": "<layer_type>",
      "enabled": false,
      "weight": 0,
      "options": {},
      "createdAt": "2018-12-10T13:45:00.000Z",
      "updatedAt": "2018-12-10T13:45:00.000Z"
    }
  }
}
```

#### Source

Voir [`internal/admin/layer_route.go#getLayer()`](../../../internal/admin/layer_route.go#getLayer)

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

Modifier un layer

#### Paramètres

- `{proxyName}` - Nom du proxy parent
- `{layerName}` - Nom du layer

#### Exemple de corps de requête

```json
{
  "weight": 100, // OPTIONNEL - Poids à associer au layer
  "enabled": true, // OPTIONNEL - Activer/désactiver le layer
  "options": {} // OPTIONNEL - Modifier les options associées au layer, voir doc/fr/references/layers
}
```

#### Exemple de résultat

```json
{
  "data": {
    "layer": {
      "name": "mylayer",
      "type": "<layer_type>",
      "enabled": false,
      "weight": 0,
      "options": {},
      "createdAt": "2018-12-10T13:45:00.000Z",
      "updatedAt": "2018-12-10T13:45:00.000Z"
    }
  }
}
```

#### Source

Voir [`internal/admin/layer_route.go#updateLayer()`](../../../internal/admin/layer_route.go#updateLayer)

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

Lister les layers existants

#### Paramètres

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

#### Exemple de résultat

```json
{
  "data": {
    "layers": [
      {
        "name": "mylayer",
        "weight": 0,
        "enabled": false,
        "createdAt": "2018-12-10T13:45:00.000Z",
        "updatedAt": "2018-12-10T13:45:00.000Z"
      }
    ]
  }
}
```

#### Source

Voir [`internal/admin/layer_route.go#queryLayers()`](../../../internal/admin/layer_route.go#queryLayers)

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

Supprimer le layer

#### Paramètres

- `{proxyName}` - Nom du proxy parent
- `{layerName}` - Nom du layer

#### Exemple de résultat

```json
{
  "data": {
    "layerName": "mylayer"
  }
}
```

#### Source

Voir [`internal/admin/layer_route.go#deleteLayer()`](../../../internal/admin/layer_route.go#deleteLayer)

### `GET /api/v1/definitions/layers?types={type1,type2,...}`

Lister les définitions des types de layer disponibles.

#### Paramètres

- `{types}` - Optionnel - Liste des types de layer à appliquer en tant que filtre

#### Exemple de résultat

```json
{
  "data": {
    "definitions": [
      {
        "type": "queue",
        "options": {
          "type": "object",
          "properties": {
            "capacity": {
              "title": "Capacité d'accueil de la file d'attente",
              "default": 1000,
              "type": "number",
              "minimum": 0
            },
            "keepAlive": {
              "title": "Temps de vie d'une session utilisateur sans activité",
              "description": "Durée sous forme de chaîne de caractères. Voir https://pkg.go.dev/time#ParseDuration pour plus d'informations.",
              "default": "1m",
              "type": "string"
            },
            "matchURLs": {
              "title": "Liste de filtrage des URLs sur lesquelles le layer est actif",
              "description": "Par exemple, si vous souhaitez limiter votre layer à l'ensemble d'une section '`/blog`' d'un site, vous pouvez déclarer la valeur `['*/blog*']`. Les autres URLs du site ne seront pas affectées par ce layer.",
              "default": ["*"],
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false
        }
      }
    ]
  }
}
```