Gyro API'ye ilk adım: API anahtarı oluşturma, kapsamlar ve ilk istek

1. Gyro API ne yapar?

Gyro Public API, müşteri panelinde yaptığınız işlerin çoğunu programla yapmanızı sağlayan bir REST API'dir: bulut sunucu siparişi ve yönetimi (güç, yeniden kurulum, snapshot, yedek, ters DNS, güvenlik duvarı), SSH anahtarları, fatura ve bakiye, alan adı ve DNS, destek talepleri, Kurumsal Mail, Nesne Depolama, Uptime İzleme ve tüm hizmetleriniz için ortak bir araç köprüsü.

Bu rehber ilk 10 dakikayı anlatır; her ucun ayrıntısı geliştirici belgelerindedir.

2. API anahtarı oluşturma

1. Müşteri paneline girin. Sağ üstteki hesap menüsünü açıp API Kimlik Bilgileri'ne tıklayın.
2. API Anahtarı Oluştur'a basın. Kimliğinizi yeniden doğrulamanız istenebilir (Siz Olduğunuzu Doğrulayın); parolanızla ya da gelen kodla onaylayın.
3. Ad alanına anahtarın nerede kullanılacağını yazın (ör. "CI sunucusu", "Yedekleme betiği").
4. İzinli IP Adresleri'ne anahtarı kullanacak makinelerin IP adreslerini her satıra bir tane yazın. Boş bırakırsanız anahtar her IP'den çalışır.
5. İzinler listesinden yalnız ihtiyacınız olanları seçin (Bölüm 4). İzinler kategorilere ayrılmıştır (Hesap, Hizmetler, Alan Adları, Faturalar …); İzinlerde ara... kutusuna cloud yazarak bulut sunucu izinlerini bulabilirsiniz. Okuma ile başlamak en güvenli yoldur.
6. Oluşturun. API Anahtarı Oluşturuldu penceresindeki anahtarı Kopyala ile alın ve bir parola yöneticisinde ya da CI sistemindeki gizli değişkenlerde saklayın.

Anahtarlarınızın listesinde her anahtarın durumu (Aktif, İptal Edildi), izin sayısı, IP kısıtı ve son kullanım zamanı görünür. İstek Kayıtları sekmesinde anahtarlarınızla yapılan her istek durum kodu, IP ve süreyle listelenir; beklemediğiniz bir erişimi buradan fark edersiniz.

3. İlk istek

Anahtarı bir ortam değişkenine koyun (komut geçmişinize düşmemesi için):

read -rs GYRO_TOKEN && export GYRO_TOKEN

Anahtarın kim olduğunu ve izinlerini sorun:

curl -s https://www.gyrohosting.com/api/v1/client/whoami \
  -H "Authorization: Bearer $GYRO_TOKEN"

Bulut sunucularınızı listeleyin:

curl -s https://www.gyrohosting.com/api/v1/client/cloud/servers \
  -H "Authorization: Bearer $GYRO_TOKEN"

Python ile aynı istek:

import os, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/servers", headers=h, timeout=60)
r.raise_for_status()
for s in r.json()["data"]:
    print(s["id"], s.get("hostname"), s.get("status"))

Sunucu numarası (id), müşteri panelindeki hizmet numarasıyla aynıdır.

4. İzinler (kapsamlar)

Her anahtar yalnız verdiğiniz izinleri taşır. Bulut sunucu işlemleri için temel izinler:

Bunların yanında alan adı, DNS, destek talebi, sipariş ve hesap işlemleri için uç başına ayrı izinler vardır; liste her izni HTTP yöntemi ve yoluyla (ör. GET /client/me) gösterir.

Önerilen anahtar düzeni:

• İzleme ve raporlama betikleri: yalnız cloud_read.
• Dağıtım (deploy) hattı: cloud_read + cloud_write, IP kısıtlı.
• Sunucu açıp kapatan altyapı otomasyonu (ör. Terraform): ayrıca cloud_order ve cloud_delete; yalnız bu iş için ayrı bir anahtar.

5. Yanıtlar, hatalar ve hız sınırı

Başarılı yanıt {"data": …, "meta": {…}}, hata {"error": {"code": "…", "message": "…", "details": {…}}} biçimindedir. Programınızda mesaja değil code alanına göre karar verin; mesajlar hesabınızın dilindedir.

Hız sınırı: anahtar başına varsayılan dakikada 60 istek. Her yanıtta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. Sınırın çok üzerine çıkan anahtar geçici olarak kilitlenir; ağır sunucu işlemleri (yeniden kurulum, geri yükleme) ayrıca sunucu başına günlük sınırlıdır.

Sayfalama: listeler page ve limit (en çok 100) alır; yanıttaki meta.next_page 0 ise son sayfadasınız.

Eşzamansız işler: kurulum, güç ve snapshot işlemleri arka planda çalışır. GET /cloud/servers/{id} ile 5-10 saniyede bir durumu sorgulayın; live.locked true iken yazma istekleri 409 döner.

6. Para harcayan ve geri dönüşsüz işlemler

API, yanlışlıkla iki sunucu sipariş etmenizi ya da veri silmenizi önlemek için üç güvenlik katmanı kullanır:

1. Önce teklif: sipariş gövdesine "dry_run": true ekleyin; fiyat teklifi döner, hiçbir şey oluşturulmaz.
2. Açık onay: gerçek sipariş ve yıkıcı işlemler (yeniden kurulum, snapshot'tan dönüş, silme) "confirm": true olmadan çalışmaz.
3. Tekrar koruması: siparişlerde Idempotency-Key başlığı zorunludur. Ağ hatasında aynı anahtar ve aynı gövdeyle tekrar denerseniz ikinci sipariş verilmez; ilk yanıt döner (Idempotency-Replayed: true).

# Önce fiyat teklifi (hiçbir şey oluşturulmaz)
curl -s -X POST https://www.gyrohosting.com/api/v1/client/cloud/servers \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"product_id": 814, "cycle": "monthly", "image": "ubuntu-24.04", "dry_run": true}'

product_id, sipariş sayfasının adresindeki numaradır (ör. /siparis/server/814); sipariş verilebilen ürünleri GET /cloud/products ile de listeleyebilirsiniz. Ürün numarası yerine paket adı ve bölgeyle de sipariş verebilirsiniz: "plan": "standart-2-4", "region": "eu-de-1". Her ürünün plan ve region değeri GET /cloud/products yanıtında yazar; bölgelerin listesi ve şehirleri GET /cloud/locations ile görünür.

7. Anahtar güvenliği

• Her kullanım yeri için ayrı anahtar oluşturun; bir yer ele geçirilirse yalnız o anahtarı iptal edersiniz.
• Sabit IP'li sunuculardan kullanılan anahtarları İzinli IP Adresleri ile kısıtlayın.
• Kullanılmayan anahtarları Anahtarı İptal Et ile iptal edin. İptal anında geçerlidir ve geri alınamaz; iptal edilen anahtar silinebilir.
• İstek Kayıtları'nı ara sıra gözden geçirin.

8. Sık sorulan sorular