REST API’ye genel bakış

REST API, konsolun arkasındaki HTTP API’sidir: konsol kendi isteklerini bu API’ye gönderir. API’yi bir taşıyıcı (bearer) kimlik bilgisiyle çağırır, JSON gönderip alırsınız; kaynakların çoğuna ait oldukları proje üzerinden erişirsiniz.

Temel URLBağlantıyı kopyalayın

API, konsolun ana bilgisayar adında değil, kendi ana bilgisayar adında (API ana bilgisayar adı) /api/v1 altında sunulur:

https://<api-host>/api/v1

• <api-host>: API’nin ana bilgisayar adı. Konsolun ana bilgisayar adı değildir.

Bu dokümantasyondaki ve API referansı içindeki her yol bu temel URL’ye göredir. Sanal makine oluşturma sihirbazının son adımındaki REST eşdeğeri bölümü, aynı yol ve gövdeyle bir curl komutudur. Bu komut konsolun ana bilgisayar adına gönderilir: API’yi kendi kodunuzdan çağırmak için API ana bilgisayar adını kullanın.

Etkileşimli API gezginiBağlantıyı kopyalayın

API ana bilgisayar adı, API referansını tarayıcınızdan istek gönderebileceğiniz etkileşimli bir sayfa olarak da sunar:

https://<api-host>/docs

Authorize düğmesini seçin, bir API belirteci veya hizmet hesabı anahtarı girin, ardından bir işlemde Try it out düğmesini kullanın. İstekler kimlik bilginizle API ana bilgisayar adına gider ve gerçek kaynaklarınız üzerinde çalışır; bu nedenle okuma işlemleriyle veya test için kullandığınız bir projeyle başlayın. Sayfa kimlik bilgisini yalnızca sayfayı yeniden yükleyene veya kapatana kadar tutar. Sayfanın dayandığı OpenAPI belgesi https://<api-host>/openapi.json adresindedir; bir istemci oluşturmak veya API’yi bir API aracına aktarmak için kullanın.

Bu sitedeki API referansı aynı işlemleri açıklar ve istek göndermez.

KapsamlarBağlantıyı kopyalayın

Kaynakların çoğu bir projeye aittir ve yolları /scopes/ ile, ardından projenin ID’siyle başlar:

/scopes/<project-id>/compute/instances

• <project-id>: kaynakları barındıran projenin ID’si.

Proje ID’sinden sonraki bölüm, compute, storage veya network gibi hizmeti belirtir. Birkaç yol bir projenin altında değildir; örneğin /operations/<operation-id>. Tam yol yapısı ve bir projenin ID’sinin nasıl bulunacağı için bkz. Kapsamlar, URL’ler ve istek biçimi.

Kimlik doğrulamaBağlantıyı kopyalayın

Her istek Authorization başlığında bir kimlik bilgisi taşır: pc_live_ ile başlayan bir API belirteci ya da sak_live_ ile başlayan bir servis hesabı anahtarı. API ağ geçidi, istek bir hizmete ulaşmadan önce her istekte kimlik bilgisini ve bir projenin kaynakları için o projeye erişiminizi denetler. Ayrıntılar için bkz. API belirteçleriyle kimlik doğrulama.

Eşzamanlı ve eşzamansız isteklerBağlantıyı kopyalayın

Okuma istekleri sonuçla birlikte 200 OK döndürür. Yazma istekleri iki şekilde yanıt verir:

• Eşzamanlı. Yanıt geldiğinde değişiklik tamamlanmıştır: sonuçla birlikte 200 OK veya 201 Created ya da 204 No Content.
• Eşzamansız. Platform isteği kabul eder ve işi daha sonra bulutta gerçekleştirir. Yanıt 202 Accepted olur. Örneğin sanal makine veya disk oluşturma, sanal makine silme ve sanal makineyi başlatma veya durdurma bu şekilde çalışır.

API referansı, her işlemin başarılı yanıt durumunu gösterir.

202 Accepted yanıtının gövdesi iki türden biridir:

202 Accepted yanıtındaki işlem zaten SUCCEEDED durumundaysa iş tamamlanmıştır. Bütçe veya taahhüt oluşturma gibi faturalandırma yazma işlemleri bu şekilde yanıt verir ve bunların işlemleri sonradan okunamaz.

Bir işlem, tek bir eşzamansız isteği izler. İşlemi GET /operations/<operation-id> ile okuyun:

{
  "id": "3f2b8c1e9d4a4f6b8e2c7a1d5b9e0f42",
  "action": "compute.instance.stop",
  "state": "RUNNING",
  "resourceKind": "instance",
  "resourceId": "9c1d6e2a7b3f4c8d9e0a1b2c3d4e5f60",
  "resourceName": "web-01",
  "createdAt": "2026-10-08T09:30:00Z",
  "startedAt": "2026-10-08T09:30:01Z",
  "updatedAt": "2026-10-08T09:30:01Z"
}

SUCCEEDED, FAILED ve CANCELLED son durumlardır. Bitmemiş bir işlemi iptal etmek için Idempotency-Key başlığıyla POST /operations/<operation-id>/actions/cancel gönderin. Zaten bitmiş bir işlemi iptal etmek 409 Conflict döndürür.

Bir işlemi yalnızca işlemin kaynağını kendi projesinde okuyabiliyorsanız okuyabilirsiniz; aksi hâlde API 404 Not Found yanıtı verir. İşlemi iptal etmek için o kaynağı yönetme izniniz olmalıdır.

Yanıtlardaki zaman damgaları, örnekteki gibi UTC’ye göre ISO 8601 dizeleridir.

Idempotent yazma işlemleriBağlantıyı kopyalayın

Her yazma isteğiyle bir Idempotency-Key başlığı gönderin. Ağ kesilirse ve bir isteğin ulaşıp ulaşmadığını bilmiyorsanız isteği aynı anahtarla yeniden gönderin: platform, değişikliği ikinci kez uygulamak yerine ilk isteğin sonucunu döndürür. Birkaç işlem anahtarı yok sayar. Kurallar ve istisnalar için bkz. Idempotent istekler. Bir API belirteci veya servis hesabı anahtarıyla, kaynak oluşturan bir POST isteği anahtar olmadan reddedilir: IDEMPOTENCY_KEY_REQUIRED koduyla 400 Bad Request. Diğer yazma isteklerinde anahtar isteğe bağlıdır.

Eşzamanlılık denetimiBağlantıyı kopyalayın

Birçok kaynak, okuduğunuzda bir ETag başlığı döndürür. Okuduğunuz sürümü değiştirdiğinizden emin olmak için bu değeri güncellemeyle birlikte bir If-Match başlığında gönderin. Kaynak bu arada değiştiyse güncelleme 412 Precondition Failed döndürür: kaynağı yeniden okuyun ve güncellemeyi tekrarlayın.

curl -X PATCH "https://<api-host>/api/v1/scopes/<project-id>/compute/instances/<instance-id>" \
  -H "Authorization: Bearer $PC_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'If-Match: <etag>' \
  -H "Content-Type: application/json" \
  -d '{"name": "web-02"}'

• <instance-id>: sanal makinenin ID’si.
• <etag>: sanal makineyi son okuduğunuzda aldığınız ETag başlığının tam değeri; örneğin W/"3a7bd3e2360a3d29eea436fcfb7e44c735d117c4".
• PC_TOKEN: API belirtecinizi tutan bir ortam değişkeni.

Şu güncellemeler If-Match gerektirir. Başlık olmadan da 412 Precondition Failed döndürürler:

• Sanal makine, disk, ağ, alt ağ, yönlendirici, güvenlik grubu, ağ arabirimi veya yük dengeleyici güncelleme.
• Yedekleme planı güncelleme veya silme.

Alt ağ için alt ağın bağlı olduğu ağın ETag değerini gönderin. Alt ağların kendi ETag değeri yoktur; alt ağ güncellemesi, ağın yeni ETag değerini döndürür.

Listeler ve sayfalamaBağlantıyı kopyalayın

Listeleme işlemleri öğeleri data içinde, sayfalama durumunu meta içinde döndürür. Ayrıntılar için bkz. Sayfalama.

Hatalar ve hız sınırlamaBağlantıyı kopyalayın

API’nin hata yanıtları ortak bir JSON yapısı kullanır: makine tarafından okunabilir bir code, bir message ve yeniden deneme başarılı olabilecekse "retryable": true. İstekleri çok hızlı gönderirseniz API, Retry-After başlığıyla 429 Too Many Requests döndürür. Bir API belirteci veya servis hesabı anahtarıyla yapılan her isteğin yanıtı X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını taşır; X-RateLimit-Reset, limitin sıfırlanmasına kalan saniye sayısıdır. Kodlar ve bunların nasıl ele alınacağı için bkz. Hatalar.

İstek ID’leriBağlantıyı kopyalayın

Her yanıt bir X-Request-Id başlığı taşır. X-Request-Id başlığını kendiniz gönderirseniz API sizin değerinizi kullanır; aksi hâlde bir değer oluşturur. Bir istekle ilgili sorun bildirirken bu ID’yi belirtin.

Sürümleme ve değişikliklerBağlantıyı kopyalayın

API, v1 içinde yalnızca geriye dönük uyumlu şekillerde değişir. Uyumluluğu bozan bir değişiklik en az 6 ay önceden duyurulur ve etkilenen işlemin yanıtları Deprecation ve Sunset başlıklarını taşır. Kurallar için bkz. API sürümleme ve kullanımdan kaldırma. Değişiklikler için bkz. API değişiklik günlüğü.

İlgili görevlerBağlantıyı kopyalayın

• API belirteçleriyle kimlik doğrulama
• Kapsamlar, URL’ler ve istek biçimi
• Idempotent istekler
• API sürümleme ve kullanımdan kaldırma
• API değişiklik günlüğü
• API referansı