Kurallar

Tüm /api/v1 uçlarında ortak davranış — hata gövdeleri, durum kodları, sayfalama, filtreler, sıralama, deneme çalıştırma, içerik türleri ve yayın zamanlaması.

Hatalar

Her başarısızlık aynı gövdeyi döndürür:

{
  "error": {
    "code": "invalid_input",
    "message": "insan tarafından okunabilir metin",
    "params": {},
    "details": {}
  }
}

code kararlıdır ve dallanma için güvenlidir. message istek diline göre yerelleştirilir ve değişebilir. Sunucu belirli bir alanı işaret edebildiğinde details bulunur ve doğrulama hatalarında genellikle path taşır.

Yaygın kodlar ve durumları:

Kod	Durum	Anlam
`invalid_input`	400	Gövde veya sorgu doğrulamadan geçemedi. `details.path` kontrol edin.
`unauthorized`	401	Belirteç yok veya süresi dolmuş.
`invalid_credentials`	401	E-posta veya parola yanlış.
`forbidden`	403	Kimlik doğrulandı ama rol dilimi bu işlemi reddediyor.
`not_found`	404	Kaynak yok veya göremiyorsunuz.
`conflict`	409	Yazma mevcut durumla çakışıyor.

object.field.required, design.block_not_found veya page.not_found gibi alan kodları aynı zarfı kullanır. Tam liste Hata kodları sayfasındadır.

Sayfalama

Liste uçları page (1 tabanlı) ve pageSize kabul eder. pageSize üst sınırı 100'dür. Sayfalanan yanıtlar satırlarla birlikte toplamı döndürür.

Dosyalar gibi imleçle sayfalanan uçlar bunun yerine cursor döndürür; devam etmek için önceki cursor değerini geri gönderin.

Filtreler ve sıralama

Nesne kayıtları search, filterField/filterOperator/filterValue veya daha zengin filters dizisini, ayrıca sortBy ve sortDirection kabul eder. Filtreler AND ile birleşir. Noktalı yollar ilişkili kaydın alanını okur.

Operatör takma adları: equals/eq, not_equals/neq, greater_than/gt, less_than/lt, gte/lte.

Deneme çalıştırma

dryRun kabul eden yazmalar doğrular, neyin değişeceğini bildirir ve hiçbir şey yazmaz. Ajan emin değilse kullanın: gerçek yazmanın döndüreceği hataları yan etkisiz döndürür.

İçerik türleri

JSON uçları application/json bekler. Dosya yüklemeleri şunlardan birini kullanır:

dosya ucuna multipart/form-data,
büyük dosyalar için create_upload_url ile alınan imzalı PUT ve ardından complete_upload,
mevcut bir varlığı çekmek için import-url / from-url.

Yayın zamanlaması

Sayfa veya chrome kaydetmek hemen bir revizyon yazar, ancak genel HTML kayıttan yaklaşık 60 saniye sonrasına kadar (expectedLiveBy) önceki veri isteği sonucunu sunabilir. publishStatus belirli bir revizyonun o yol için şu anda sunulan revizyon olup olmadığını söyler.