Başlangıç

Cubicl API entegrasyon dokümanı

Cubicl API'yını işlerinizi otomatize etmek veya Cubicl'ı kendi sisteminiz de dahil olmak üzere diğer yazılımlarla entegre etmek için kullanabilirsiniz. Görevleri, müşterileri, dosyaları ve diğer kayıtları listelemek, oluşturmak, düzenlemek ve silmek için HTTP istekleri gönderebilirsiniz. Bu doküman teknik bilgiler içerdiği için eğer bilginiz yoksa bu belgeyi bir geliştiriciye yönlendirmelisiniz.

Protokol

Cubicl, RESTful tabanlı API kullanır. JSON, istek gövdesi ve yanıtlar için kullanılır. API URL'leri https://cubicl.io/api/v1/ ile başlar. Örneğin bir görev oluşturmak için aşağıdaki URL'ye bir istek göndermelisiniz:

https://cubicl.io/api/v1/tasks

Atılan isteğin sonucu başarılı ise 200 kodu veya 2 ile başlayan HTTP durum kodları döner. Hata durumunda ise aşağıdaki HTTP durum kodları döner.

400	Geçersiz İstek	İstek parametreleri eksik veya yanlış biçimde.
401	Yetkisiz	Erişim jetonu geçersiz veya eksik.
403	İzin Verilmedi	İşlemi yapmak için gerekli izinlere sahip değilsiniz.
404	Bulunamadı	Kaynak mevcut değil.
405	Yanlış metod	Yanlış HTTP metodu (GET, POST vb.) kullandınız. İstek için hangi metodun kullanıldığını görmek için API dokümanına bakın.
418	Kahve Yok	Kahve demlemeye çalışıyorsunuz ancak sunucu çaydanlık olduğu için bu isteğiniz yerine getirilemiyor.
422	Geçersiz İstek	Mümkün olmayan veya mantıklı olmayan bir şey yapmaya çalışıyorsunuz. Üzerinde çalıştığınız verileri kontrol edin.
429	Çok Fazla İstek	Kısa bir süre içinde çok fazla istek gönderdiniz. Bir dakika içinde 120'den fazla istek gönderemezsiniz. Biraz bekleyin ve tekrar deneyin.
5xx	Sunucu Hatası	Sunucuda bir hata oluştu.

Bir dakika içinde 60'tan fazla istek gönderemezsiniz. Bir döngü içinde göndermeyi planlıyorsanız, istekler arasına bir gecikme koyun.

Erişim Jetonları

Cubicl, API erişimi için Bearer kimlik doğrulama şemasını kullanır. API'mize istek göndermek için Entegrasyonlar sayfasından bir erişim jetonu oluşturmalısınız. İstek gönderirken, yetkilendirme adlı bir başlıkta erişim jetonunu şu şekilde gönderin:

Authorization: Bearer ERİŞİM_JETONUNUZ

Erişim jetonları, bir kullanıcı adına istek göndermenize (verilere erişme veya işlem yapma) izin verir. Dolayısıyla oluşturulan bu jetonlar hassas verilerdir ve parola olarak ele alınmaları gerekir. Bunları başkalarıyla PAYLAŞMAYIN. Bunları PAYLAŞILAN VE HERKESİN GÖRDÜĞÜ PROJELERE EKLEMEYİN. Cubicl arayüzünden bu jetonları kaldırarak erişimi kesebilirsiniz.

İzinler

Erişim jetonları bir kullanıcı adına erişime izin verdiğinden dolayı ilgili kullanıcının bu eylemi gerçekleştirmek için gerekli izinlere sahip olması gerekir. Kullanıcı izinleri, Cubicl arayüzünden ayarlanır. Erişim jetonları her kullanıcı için ayrı ayrı oluşturulur. Bundan dolayı, adına istek göndereceğiniz kullanıcının hesabında jeton oluşturmanız gerekir.

Ayrı Hesap

API istekleri aracılığıyla gerçekleştirilen görev oluşturma gibi eylemler, erişim jetonlarının sahibi tarafından yapılmış gibi görünmektedir. Otomatikleştirilmiş API işlemlerini kullanıcının kendi eylemlerinden ayırmanız gerekiyorsa, yalnızca API erişimi için yeni bir kullanıcı hesabı oluşturmayı düşünebilirsiniz. API entegrasyon uygulamanız, bir kullanıcıya vermek istediğiniz çok çeşitli izinler gerektiğinde de bu dikkate alınmalıdır. Normal bir kullanıcı hesabından hiçbir farkı olmadığı için bu hesaplar için de aylık veya yıllık abonelik ücretleri geçerlidir.

Veriler ve Gösterimi

İlerleyen sayfalarda, API bağlantıları ile ilgili ayrıntıları göreceksiniz. Bir istekte gönderilen ve sunucudan dönen verilerin özellikleri ve formatı burada açıklanmaktadır.

Gösterim

Veriler, burada Typescript programlama dili ile gösterilmiştir. Aşağıda yorum satırlarıyla birlikte bir örnek verilmiştir.

type Task = {
    // Özellik adları ve tipleri, anahtar-tip çiftleri olarak gösterilir
    name: string,
    activityCount: number,
    completed: boolean,
    // Nesne türleri, özelliklerinin her birinin tipini tanımlar
    progress: {
        totalSteps: number,
        completed: number,
    },
    // Dizi tiplerinde, tip adının yanında köşeli parantezler vardır. Özelliklerin
    // bir dizi nesneyi veya bir dizi diziyi de tutabileceğini unutmayın.
    assigneeIds: string[],
    // Bir alan boş olabiliyorsa, özellik adının yanında "?" eklenir.
    // Alan hem boş olabilir hem de farklı tipler içerebilirse "|"
    // sembolü ile gösterilir.
    archivedAt?: Date | null,
}

ID'ler

Kayıtların ID'si string tipinde _id ile gösterilir. Örnek:

627fd586f8b23768c7261a63

Tarih Değerleri

İsteklerdeki ve yanıtlardaki tarihler, saniye cinsinden Unix Tarih Bilgisi olarak gönderilir. Bundan dolayı API dokümanında tipi number olarak gösterilir.

Seyrek Veriler

Aksi belirtilmedikçe, oluşturma ve güncelleme istekleri yalnızca gerekli alanları zorunlu kılar. İsteklerde diğer alanların gönderilmesi gerekmez.

Sunucudan döndürülen kayıtlar, daha önce ayarlanmamışsa tüm alanları içermeyebilir. Kodunuz eksik alanları işleyebilmelidir. Bu durumda, bunları boş veya yanlış bir değer olarak kabul edin.

Yardım

API dokümanı, erişim jetonu oluşturma ile ilgili herhangi bir sorunla karşılaşırsanız veya eksik bir uç noktasının eklenmesini istiyorsanız lütfen bizimle iletişime geçin.