> 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/reference/getting-started/beginners-guide-payload-headers-and-example-request.md).
# Guide du débutant : Payload, en-têtes et exemple pratique
## Qu’est-ce qu’un payload et comment est-il utilisé dans une requête API ?
Lorsque vous envoyez une requête à une API, vous devez parfois inclure des informations pour que l’API sache exactement ce que vous voulez qu’elle fasse. Ces informations sont envoyées dans le corps de la requête, et elles s’appellent le **charge utile** .
Vous pouvez considérer la charge utile comme le « contenu du colis » : la requête est l’enveloppe, et la charge utile est ce qu’elle contient.
Dans ce cas, la charge utile est un **JSON** fichier contenant les données nécessaires pour créer un disque et le rattacher à un serveur.
***
## Un exemple pratique
Nous l’expliquerons à l’aide de l’exemple suivant
### Le point de terminaison que nous utiliserons
Le point de terminaison est :
/api/servers/v1/subscriptions/\[subscriptionId]/disks
Ce point de terminaison est utilisé pour **créer un nouveau disque** dans un abonnement et **le rattacher à un serveur**.
**Qu’est-ce que** \[subscriptionId] ? Cette valeur fait partie de l’URL, pas du payload. Cela signifie que vous devez remplacer \[subscriptionId] par l’ID réel de votre abonnement.
Exemple :
/api/servers/v1/subscriptions/abc123/disks
***
### Que contient le payload ?
Le payload JSON que vous envoyez doit inclure ces paramètres :
**serverId** → L’ID du serveur auquel le disque sera rattaché
**name** → Le nom que vous voulez donner au disque
**zone** → La zone où le disque sera créé
**size** → La taille du disque (par exemple, 25 Go)
Voici le modèle JSON de base :
JSON
```json
{
"serverId": null,
"name": null,
"zone": "",
"size": 25
}
```
Dans une requête réelle, vous remplaceriez les valeurs, par exemple :
```json
{
"serverId": "srv-12345",
"name": "secondary-data",
"zone": "eu-madrid-1",
"size": 25
}
```
***
### En-têtes requis dans la requête
En plus du payload, votre requête doit inclure des en-têtes spécifiques pour que l’API puisse le traiter correctement :
Authorization: Bearer \[your-access-token] Accept: application/json Content-Type: application/json
Ces en-têtes ont la fonction suivante :
**Authorization** → Vous identifie à l’aide d’un **jeton**
**Accept** → Indique à l’API que vous voulez la réponse en JSON
**Content-Type** → Indique que votre payload est également en JSON
***
### Exemple complet en cURL
Voici une **POST** requête complète utilisant cURL :
Bash
```curl
curl -X POST "https://your-domain.com/api/servers/v1/subscriptions/abc123/disks" \
-H "Authorization: Bearer my-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"serverId": "srv-12345",
"name": "secondary-data",
"zone": "eu-madrid-1",
"size": 25
}'
```
**Que se passe-t-il ici ?**
* -X POST → Vous indiquez à l’API que vous voulez **créer** quelque chose.
* L’\*\*URL\*\* inclut le \[subscriptionId] (abc123).
* Les lignes -H envoient les **en-têtes** .
* Le bloc -d envoie le **charge utile** sous forme d’objet JSON.
***
### Exemple pour Windows dans PowerShell
Ci-dessous se trouve la **même requête utilisant** curl.exe **dans Windows PowerShell** . Elle envoie une requête POST pour créer un disque et le rattacher à un serveur, en incluant les en-têtes requis et un payload JSON.
PowerShell
```powershell
$subscriptionId = "abc123"
$token = "my-secret-token"
$baseUrl = "https://your-domain.com"
$endpoint = "/api/servers/v1/subscriptions/$subscriptionId/disks"
$url = "$baseUrl$endpoint"
# Corps JSON sous forme de chaîne littérale ici (plus facile à écrire sans échapper les guillemets)
$jsonBody = @'
{
"serverId": "srv-12345",
"name": "secondary-data",
"zone": "eu-madrid-1",
"size": 25
}
'@
# Requête POST avec curl.exe
curl.exe -X POST $url `
-H "Authorization: Bearer $token" `
-H "Accept: application/json" `
-H "Content-Type: application/json" `
-d $jsonBody
```
**Ce que cela fait**
* Place subscriptionId dans l’URL (pas dans le JSON).
* Envoie l’en-tête Authorization avec votre jeton d’accès.
* Définit Accept: application/json et Content-Type: application/json.
* Envoie le payload (JSON) avec les champs requis : serverId, name, zone, size.
**Astuce facultative**
Si vous souhaitez insérer des variables directement dans le JSON, utilisez une here-string extensible (@" ... "@) plutôt que la littérale :
PowerShell
```powershell
$serverId = "srv-12345"
$jsonBody = @"
{
"serverId": "$serverId",
"name": "secondary-data",
"zone": "eu-madrid-1",
"size": 25
}
"@
```
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.plenit.com/fr/reference/getting-started/beginners-guide-payload-headers-and-example-request.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.