Sıfırdan Başlangıç

PHP bilen bir geliştiricinin sıfırdan entegrasyon kurabilmesi için öğretici rehber.

Bu sayfa sadece endpoint referansı vermez; entegrasyonu hangi sırayla kurmanız gerektiğini, hangi header’ların zorunlu olduğunu, task tabanlı yapının nasıl çalıştığını ve aynı akışın PHP, Node.js ve Python tarafında nasıl yazılacağını anlatır.

Temel Mantık

Public API token ile çalışır. Listeleme ve sorgulama uçları doğrudan veri döner, ağır işlemler task döner.

Zorunlu Header’lar

Auth için `Authorization: Bearer ...`. Yan etkili isteklerde ayrıca `Idempotency-Key` gerekir.

Takip Modeli

Provision, format ve snapshot gibi işlemlerde yanıtı aldıktan sonra task endpoint’inden durumu izlersiniz.

Hazır Kullanılabilir Dosyaları İndirin

Kod bloklarını elle kopyalamak istemiyorsanız, hazırlanmış istemci dosyalarını ve Postman collection dosyasını doğrudan indirebilirsiniz.

PHP Client

Düz PHP + cURL başlangıç istemcisi.

php-client.php

Node.js Client

Fetch tabanlı başlangıç istemcisi.

node-client.mjs

Python Client

Requests tabanlı başlangıç istemcisi.

python-client.py

Postman: yamanvm-public-api.postman_collection.json

1. Entegrasyonu Kurma Sırası

Token alın.

Admin panelde `YamanVM Yönetimi > API İstemcileri` ekranından bir API client oluşturun. Token sadece oluşturulduğu anda düz metin olarak görünür.

Base URL belirleyin.

Bu kurulum için base URL şu an `https://denemevm.yamanhosting.com`. API prefix’i `/api/v1` olduğu için ping adresi `https://denemevm.yamanhosting.com/api/v1/ping`.

Önce ping ile doğrulayın.

İlk gerçek test olarak `GET /api/v1/ping` çağrısı yapın. Auth, header ve network problemlerini önce burada ayıklayın.

Sunucuları listeleyin.

Entegrasyonun temel veri okuma akışı için `GET /api/v1/servers` kullanın. Ardından gerekirse `GET /api/v1/servers/{server}` ve task uçlarına geçin.

Mutating işlemlerde idempotency kullanın.

Provision, format, power ve snapshot isteklerinde `Idempotency-Key` gönderin. Timeout veya retry durumunda aynı işlemin iki kere çalışmasını engeller.

Önemli: Provision ve format gibi ağır işlemler senkron bitmez. API task kaydı döner. Sonucu `GET /api/v1/tasks/{id}` veya `GET /api/v1/servers/{server}/tasks` ile takip edersiniz.

2. Her İstekte Bilmeniz Gerekenler

Authentication

Authorization: Bearer yvm_live_xxxxxxxxx

Request ID

X-Request-Id: ext-req-1001

Destek ve log takibi için faydalıdır. Response’ta da geri döner.

Idempotency

Idempotency-Key: order-1001-format

Sadece yan etkili isteklerde zorunludur.

3. PHP How-To

Bu bölüm özellikle PHP bilen ama API entegrasyonu tarafında yönlendirmeye ihtiyaç duyan geliştiriciler için yazıldı. `curl` ile başlayıp isterseniz bunu daha sonra Guzzle gibi bir istemciye taşıyabilirsiniz.

Download PHP SDK class

3.1 Ortak istek yardımcı fonksiyonu

<?php
function yamanvmRequest(
    string $method,
    string $path,
    string $token,
    ?array $payload = null,
    ?string $idempotencyKey = null
): array {
    $baseUrl = 'https://yamanvm.yamanhosting.com';
    $headers = [
        'Authorization: Bearer ' . $token,
        'Accept: application/json',
        'X-Request-Id: php-' . uniqid(),
    ];

    if ($idempotencyKey !== null) {
        $headers[] = 'Idempotency-Key: ' . $idempotencyKey;
    }

    if ($payload !== null) {
        $headers[] = 'Content-Type: application/json';
    }

    $ch = curl_init(rtrim($baseUrl, '/') . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => strtoupper($method),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_TIMEOUT => 30,
    ]);

    if ($payload !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload, JSON_UNESCAPED_SLASHES));
    }

    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if ($raw === false) {
        throw new RuntimeException('Curl error: ' . curl_error($ch));
    }

    curl_close($ch);

    return [
        'status' => $status,
        'body' => json_decode($raw, true),
        'raw' => $raw,
    ];
}

3.2 Ping ile auth testi

<?php
$token = 'yvm_live_xxxxxxxxxxxxxxxxx';
$result = yamanvmRequest('GET', '/api/v1/ping', $token);

if ($result['status'] !== 200) {
    print_r($result['body']);
    exit('Ping failed');
}

print_r($result['body']);

3.3 Sunucu listeleme

<?php
$token = 'yvm_live_xxxxxxxxxxxxxxxxx';
$result = yamanvmRequest('GET', '/api/v1/servers?per_page=10', $token);

foreach (($result['body']['servers'] ?? []) as $server) {
    echo $server['id'] . ' - ' . $server['name'] . PHP_EOL;
}

3.4 Task takip etme

<?php
$token = 'yvm_live_xxxxxxxxxxxxxxxxx';
$serverId = 3;

$result = yamanvmRequest('GET', "/api/v1/servers/{$serverId}/tasks", $token);

foreach (($result['body']['tasks'] ?? []) as $task) {
    echo sprintf(
        "#%d %s %s %d%%\n",
        $task['id'],
        $task['type'],
        $task['status'],
        $task['progress_percent']
    );
}

3.5 Power aksiyonu çalıştırma

<?php
$token = 'yvm_live_xxxxxxxxxxxxxxxxx';
$serverId = 3;

$result = yamanvmRequest(
    'POST',
    "/api/v1/servers/{$serverId}/power",
    $token,
    ['action' => 'restart'],
    'srv-3-restart-1001'
);

print_r($result['body']);

3.6 Provision request gönderme

<?php
$token = 'yvm_live_xxxxxxxxxxxxxxxxx';

$payload = [
    'template_id' => 7,
    'host_id' => 2,
    'disk_id' => 4,
    'cpu_count' => 2,
    'ram_gb' => 4,
    'disk_gb' => 80,
    'ip_count' => 1,
    'ip_pool_id' => 1,
    'snapshot_limit' => 3,
];

$result = yamanvmRequest(
    'POST',
    '/api/v1/provisioning/requests',
    $token,
    $payload,
    'order-1001-provision'
);

print_r($result['body']);

// Sonraki adım:
// response içindeki server.id veya task bilgisiyle takip akışına geçin.

4. Node.js How-To

Download Node.js SDK class

4.1 Basit yardımcı fonksiyon

const baseUrl = 'https://yamanvm.yamanhosting.com';
const token = 'yvm_live_xxxxxxxxxxxxxxxxx';

async function yamanvmRequest(method, path, payload = null, idempotencyKey = null) {
  const headers = {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json',
    'X-Request-Id': `node-${Date.now()}`,
  };

  if (idempotencyKey) {
    headers['Idempotency-Key'] = idempotencyKey;
  }

  if (payload) {
    headers['Content-Type'] = 'application/json';
  }

  const response = await fetch(`${baseUrl}${path}`, {
    method,
    headers,
    body: payload ? JSON.stringify(payload) : undefined,
  });

  return {
    status: response.status,
    body: await response.json(),
  };
}

4.2 Ping

const ping = await yamanvmRequest('GET', '/api/v1/ping');
console.log(ping.status, ping.body);

4.3 Format task başlatma

const formatResponse = await yamanvmRequest(
  'POST',
  '/api/v1/servers/3/format',
  {
    template_id: 7,
    admin_password: 'NewPass!123',
    confirm_reset: true,
  },
  'srv-3-format-1001'
);

console.log(formatResponse.status, formatResponse.body);

5. Python How-To

Download Python SDK class

5.1 Requests ile temel istemci

import time
import requests

BASE_URL = "https://yamanvm.yamanhosting.com"
TOKEN = "yvm_live_xxxxxxxxxxxxxxxxx"

def yamanvm_request(method, path, payload=None, idempotency_key=None):
    headers = {
        "Authorization": f"Bearer {TOKEN}",
        "Accept": "application/json",
        "X-Request-Id": f"python-{int(time.time())}",
    }

    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key

    response = requests.request(
        method,
        f"{BASE_URL}{path}",
        json=payload,
        headers=headers,
        timeout=30,
    )

    return response.status_code, response.json()

5.2 Sunucu görevlerini çekme

status, body = yamanvm_request("GET", "/api/v1/servers/3/tasks")
print(status)
print(body)

5.3 Snapshot oluşturma

status, body = yamanvm_request(
    "POST",
    "/api/v1/servers/3/snapshots",
    {
        "name": "release-before-upgrade",
        "description": "Checkpoint before upgrade",
    },
    "srv-3-snapshot-1001",
)

print(status)
print(body)

6. Hata Okuma ve Retry Mantığı

401

Token eksik veya geçersizdir. Önce auth katmanını düzeltin.

403

Token geçerli ama scope yetkisi yoktur veya IP kısıtı devrededir.

422

Payload iş kurallarına uymuyordur. `errors` alanına bakın.

Retry yapmanız gerekirse aynı işlemi aynı `Idempotency-Key` ile tekrar gönderin. Yeni anahtar üretirseniz sistem bunu yeni bir işlem olarak algılar.