> For the complete documentation index, see [llms.txt](https://docs.plenit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.plenit.com/fr/referencia/how-to-make-api-requests.md).

# Comment effectuer des requêtes à l'API

Toutes les requêtes à l'API Plenit suivent les mêmes règles : comment vous vous authentifiez, comment l'adresse est construite, comment les données sont envoyées et comment les réponses sont lues. Avec ce guide, vous pouvez lire n'importe quelle opération de la Référence et la porter dans votre script ou dans votre client HTTP.

{% hint style="success" %}

#### 👍 **Ce que vous obtenez**

Savoir construire n'importe quelle requête à l'API, paginer et filtrer les résultats, et interpréter les réponses et les erreurs.
{% endhint %}

### Avant de commencer

* Avoir un jeton API actif et sa clé enregistrée. Consultez [Comment créer un jeton API](/fr/referencia/jetons-api/how-to-create-an-api-token.md).
* Avoir effectué votre premier appel. Consultez [Accueil de l'API](/fr/referencia/api-overview.md).

### Anatomie d'une requête

Chaque requête comporte quatre parties :

| Partie   | Qu'est-ce que c'est                                                                | Exemple                                                         |
| -------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Méthode  | L'action que vous effectuez sur la ressource                                       | `GET` consulte, `POST` crée, `PATCH` modifie, `DELETE` supprime |
| Adresse  | L'adresse de base plus la ressource                                                | `https://www.plenit.com/api/servers/v1/servers`                 |
| En-têtes | L'authentification et le format des données                                        | `Authorization: Bearer <votre-token>`                           |
| Corps    | Les données que vous envoyez, uniquement lors de la création ou de la modification | Un objet JSON                                                   |

### Authentification

Toutes les requêtes portent la clé du jeton dans l'en-tête `Authorization`:

```
Authorization: Bearer <votre-token>
```

Une requête sans cet en-tête, ou avec un jeton expiré ou révoqué, n'est pas exécutée.

{% hint style="warning" %}

#### 🚧 **Ne mets jamais la clé dans l'adresse**

N'ajoutez pas le jeton comme paramètre de l'URL ni ne le stockez dans le code de vos scripts. Conservez-le dans une variable d'environnement ou dans le gestionnaire de secrets que vous utilisez.
{% endhint %}

### Comment accéder à vos ressources

La plupart des opérations de Serveurs fonctionnent dans une **abonnement**. C'est pourquoi, avant de consulter ou de gérer des serveurs, des réseaux ou des disques, vous avez besoin de l'identifiant de l'abonnement (`subscriptionId`).

Le parcours habituel est :

1. Consultez les abonnements d'une organisation avec `GET /subscriptions?organizationId=<id-organisation>`.
2. Prenez le `id` de l'abonnement qui vous intéresse.
3. Utilisez-le dans le reste des opérations, par exemple `GET /servers?subscriptionId=<id-abonnement>`.

```bash
curl "https://www.plenit.com/api/servers/v1/servers?subscriptionId=<id-abonnement>" \
  -H "Authorization: Bearer <votre-token>"
```

### Envoyer des données lors de la création ou de la modification

Les requêtes `POST` et `PATCH` transportent un corps en JSON. Ajoutez l'en-tête `Content-Type: application/json` et enveloppez les données dans un objet `data`:

```bash
curl -X POST "https://www.plenit.com/api/servers/v1/<ressource>" \
  -H "Authorization: Bearer <votre-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "champ": "valeur"
    }
  }'
```

Les champs obligatoires de chaque opération se trouvent dans la Référence.

### Paginer les résultats

Les requêtes qui renvoient des listes répondent par pages. Contrôlez la taille et la position avec ces paramètres :

| Paramètre | Ce que fait                  | Valeurs       |
| --------- | ---------------------------- | ------------- |
| `limit`   | Nombre de résultats par page | De 1 à 1000   |
| `offset`  | Nombre de résultats ignorés  | À partir de 0 |
| `page`    | Numéro de page               | À partir de 1 |

Par exemple, pour demander les résultats du 11 au 20 :

```
GET /servers?subscriptionId=<id-abonnement>&limit=10&offset=10
```

Chaque réponse indique dans `metadata.records` le total des résultats et des pages, et dans `links.pages` les adresses de la première, de la dernière, de la suivante et de la précédente. Pour parcourir tous les résultats, suivez le lien `next` jusqu'à ce qu'il soit vide.

### Trier les résultats

* `orderBy`: le champ par lequel trier, par exemple `name`.
* `order`: `asc` pour un ordre croissant ou `desc` pour décroissant.

```
GET /servers?subscriptionId=<id-abonnement>&orderBy=name&order=asc
```

### Filtrer les résultats

Chaque filtre comporte trois parties : le champ (`field`), l'opérateur (`operator`) et la valeur (`value`). Vous pouvez combiner plusieurs filtres en les numérotant à partir de 0 :

```
GET /servers?subscriptionId=<id-abonnement>
  &filters[0][field]=name
  &filters[0][operator]=CONTAINS
  &filters[0][value]=web
```

| Opérateur                   | Signification                                                     |
| --------------------------- | ----------------------------------------------------------------- |
| `=` / `!=`                  | Égal à / différent de                                             |
| `>` / `<` / `>=` / `<=`     | Supérieur à / inférieur à / supérieur ou égal / inférieur ou égal |
| `CONTAINS`                  | Contient le texte                                                 |
| `STARTS_WITH` / `ENDS_WITH` | Commence / se termine par le texte                                |
| `IN` / `NOT_IN`             | Est / n'est pas dans une liste de valeurs                         |

{% hint style="info" %}

#### 📘 **Encodez les crochets si votre outil ne le fait pas**

Postman et Insomnia encodent automatiquement l'adresse. Avec `curl`, utilisez l'option `-g` ou écrivez `%5B` et `%5D` à la place de `[` et `]`.
{% endhint %}

### Lire les réponses

Les réponses correctes ont cette structure :

* `data`: la ressource ou la liste de ressources que vous avez demandée.
* `metadata`: l'identifiant de la requête (`correlationId`), l'heure de la réponse et, dans les listes, les données de pagination.
* `links`: dans les listes, les liens vers les autres pages de résultats.

Conservez le `correlationId` lorsque quelque chose ne se passe pas comme prévu. Si vous contactez le Support, incluez-le afin qu'ils puissent localiser votre requête.

### Interpréter les erreurs

Lorsqu'une requête échoue, la réponse renvoie une liste `errors`. Chaque erreur indique un code, une description et le point de la requête qui l'a provoquée :

```json
{
  "errors": [
    {
      "code": "servers.bad_request",
      "title": "Resource request invalid.",
      "source": {
        "pointer": "/api/servers/v1/servers"
      }
    }
  ]
}
```

| Code HTTP | Ce que cela signifie                                                          | Que faire                                                                                           |
| --------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `400`     | La requête n'est pas valide : il manque un champ ou une valeur est incorrecte | Vérifiez les paramètres et le corps avec la Référence                                               |
| `500`     | Erreur interne                                                                | Répétez la requête plus tard. Si le problème persiste, contactez le Support avec le `correlationId` |

### Utiliser Postman ou Insomnia

Si vous préférez ne pas travailler depuis la ligne de commande, n'importe quel client HTTP convient. Pour chaque requête :

1. Choisissez la méthode et écrivez l'adresse complète.
2. Ajoutez l'en-tête `Authorization` avec la valeur `Bearer <votre-token>`.
3. Si la requête comporte un corps, ajoutez l'en-tête `Content-Type: application/json` et écrivez le JSON.

{% hint style="info" %}

#### 📘 **Enregistrez le jeton une seule fois**

Postman et Insomnia permettent d'enregistrer la clé comme variable d'environnement et de la réutiliser dans toutes les requêtes. Ainsi, vous ne la copiez pas à chaque requête et vous la changez à un seul endroit lorsque vous régénérez le jeton.
{% endhint %}

### Étapes suivantes

* Référence : toutes les opérations disponibles, avec leurs paramètres et exemples.
* [Questions fréquentes](/fr/referencia/api-faq.md): réponses rapides sur l'API et les jetons API.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.plenit.com/fr/referencia/how-to-make-api-requests.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.