Beginner's Guide: Payload, Headers, and a Practical Example

What Is a Payload and How Is It Used in an API Request?

When you send a request to an API, you sometimes need to include information so the API knows exactly what you want it to do. This information is sent inside the body of the request, and it is called the payload .

You can think of the payload as the “content of the package”: the request is the envelope, and the payload is what’s inside.

In this case, the payload is a JSON file that contains the necessary data to create a disk and attach it to a server.

---

A practical example

We'll explain it using the following example

The Endpoint We Will Use

The endpoint is:

/api/servers/v1/subscriptions/[subscriptionId]/disks

This endpoint is used to create a new disk inside a subscription and attach it to a server.

What Is [subscriptionId]? This value is part of the URL, not the payload. It means you must replace [subscriptionId] with the actual ID of your subscription.

Example:

/api/servers/v1/subscriptions/abc123/disks

---

What Goes Inside the Payload?

The JSON payload you send must include these parameters:

serverId → The ID of the server where the disk will be attached

name → The name you want to give the disk

zone → The zone where the disk will be created

size → The disk size (for example, 25 GB)

Here is the base JSON model:

JSON

{
  "serverId": null,
  "name": null,
  "zone": "",
  "size": 25
}

In a real request, you would replace the values, for example:

{
  "serverId": "srv-12345",
  "name": "secondary-data",
  "zone": "eu-madrid-1",
  "size": 25
}

---

Required Headers in the Request

Besides the payload, your request must include specific headers so the API can process it correctly:

Authorization: Bearer [your-access-token] Accept: application/json Content-Type: application/json

These headers have the following purpose:

Authorization → Identifies you using an access token

Accept → Tells the API that you want the response in JSON

Content-Type → Indicates that your payload is also in JSON

---

Full cURL Example

Here is a complete POST request using cURL:

Bash

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
      }'

What’s happening here?

• -X POST → You are telling the API you want to create something.
• The **URL ** includes the [subscriptionId] (abc123).
• The -H lines send the required headers .
• The -d block sends the payload as a JSON object.

---

Example for Windows in PowerShell

Below is the same request using curl.exe in Windows PowerShell . It sends a POST request to create a disk and attach it to a server, including the required headers and a JSON payload.

PowerShell

$subscriptionId = "abc123"
$token = "my-secret-token"
$baseUrl = "https://your-domain.com"
$endpoint = "/api/servers/v1/subscriptions/$subscriptionId/disks"
$url = "$baseUrl$endpoint"

# JSON body as a here-string (easier to write without escaping quotes)
$jsonBody = @'
{
  "serverId": "srv-12345",
  "name": "secondary-data",
  "zone": "eu-madrid-1",
  "size": 25
}
'@

# POST request with curl.exe
curl.exe -X POST $url `
  -H "Authorization: Bearer $token" `
  -H "Accept: application/json" `
  -H "Content-Type: application/json" `
  -d $jsonBody

What this does

• Puts subscriptionId in the URL (not in the JSON).
• Sends the Authorization header with your access token.
• Sets Accept: application/json and Content-Type: application/json.
• Sends the payload (JSON) with the required fields: serverId, name, zone, size.

Optional tip

If you want to insert variables directly into the JSON, use an expandable here‑string (@" ... "@) instead of the literal one:

PowerShell

$serverId = "srv-12345"
$jsonBody = @"
{
  "serverId": "$serverId",
  "name": "secondary-data",
  "zone": "eu-madrid-1",
  "size": 25
}
"@