bouncer/doc/fr/references/admin_api.md

399 lines
8.7 KiB
Markdown
Raw Permalink Normal View History

2023-07-08 20:19:43 +02:00
# 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.
2023-07-08 20:19:43 +02:00
## Points d'entrée
### `POST /api/v1/proxies`
Créer un nouveau proxy
#### Exemple de corps de requête
```json
2023-07-08 20:19:43 +02:00
{
"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
2023-07-08 20:19:43 +02:00
}
```
#### Exemple de résultat
```json
2023-07-08 20:19:43 +02:00
{
"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"
2023-07-08 20:19:43 +02:00
}
}
2023-07-08 20:19:43 +02:00
}
```
#### 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
2023-07-08 20:19:43 +02:00
{
"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"
2023-07-08 20:19:43 +02:00
}
}
2023-07-08 20:19:43 +02:00
}
```
#### 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
2023-07-08 20:19:43 +02:00
{
"to": "https://www.cadoles.com", // OPTIONNEL - Site distant ciblé par le proxy
2023-07-08 20:19:43 +02:00
"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
2023-07-08 20:19:43 +02:00
}
```
#### Exemple de résultat
```json
2023-07-08 20:19:43 +02:00
{
"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"
2023-07-08 20:19:43 +02:00
}
}
2023-07-08 20:19:43 +02:00
}
```
#### 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
2023-07-08 20:19:43 +02:00
{
"data": {
"proxies": [
{
"name": "myproxy",
"weight": 0,
2024-04-19 09:28:46 +02:00
"enabled": false,
"createdAt": "2018-12-10T13:45:00.000Z",
"updatedAt": "2018-12-10T13:45:00.000Z"
}
]
}
2023-07-08 20:19:43 +02:00
}
```
#### 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
2023-07-08 20:19:43 +02:00
{
"data": {
"proxyName": "myproxy"
}
2023-07-08 20:19:43 +02:00
}
```
#### Source
Voir [`internal/admin/proxy_route.go#deleteProxy()`](../../../internal/admin/proxy_route.go#deleteProxy)
2024-04-19 09:28:46 +02:00
### `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)
2024-05-17 15:44:28 +02:00
### `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
}
}
]
}
}
```