LinkHarbor API’sine genel bakış

REST API, LinkHarbor’ı kendi programlarından yönetmeni sağlar: sayfalar ve bağlantılar oluştur, taslakları düzenle ve yayınla, kısa bağlantılar üret ya da istatistikleri kendi raporlamana çek. Bu makale geliştiriciler içindir ve her uç nokta için geçerli temel kuralları açıklar.

#Hangi yol uygun?

#Temel URL ve sürümleme

Temel URL

https://dock.at-harbor.com – tüm ürün uç noktaları /v1 altındadır, örneğin https://dock.at-harbor.com/v1/pages.

Sürüm

Şu anda yalnızca v1 sürümü var. Sürüm numarası yolun parçasıdır.

Protokol

Yalnızca HTTPS.

OpenAPI

Makine tarafından okunabilir açıklama (OpenAPI 3.1) https://dock.at-harbor.com/openapi.yaml adresinde. Onu Postman’e, Insomnia’ya veya bir kod üreticiye yükleyebilirsin.

#Sandbox’ta test etme

Geliştirme ve test için ayrı bir sandbox var. Gerçek API gibi davranır ama ondan tamamen ayrıdır: kendi hesapları, kendi verileri ve hiçbiri gerçek çalışma alanına girmez.

API

https://drydock.at-harbor.com, yukarıdakiyle aynı yollarla, örneğin https://drydock.at-harbor.com/v1/pages.

Panel

https://sandbox-deck.linkharbor.com, örneğin API anahtarı oluşturmak için.

Sayfalar

Yayınlanmış sayfalar https://<handle>.sandbox.linkharbor.com adresinde görünür.

Hesap

Gerçek LinkHarbor hesabın orada çalışmaz. Ayrı bir sandbox hesabı oluştur.

Sandbox e-posta göndermez. API üzerinden kaydolursan (POST /v1/auth/register) doğrulama kodu doğrudan yanıtta, _dev_verification alanında döner. Aynısı şifre sıfırlama ve e-posta değişiklikleri için de geçerlidir. Bu alan yalnızca sandbox’ta vardır, bu yüzden kodunda ona güvenme.

• Anlık bildirimler kapalıdır
• Ödemeler Stripe’ın test modunda çalışır, gerçek para hareket etmez
• Hız limitleri gerçek değerlerin yaklaşık üçte biridir ve yeni hesaplar saatte ve IP adresi başına 5 ile sınırlıdır
• Her ayın 1’inde saat 3:00 UTC’de sandbox tamamen silinir ve ardından tüm hesaplar ve veriler gider
• Her yanıt X-Environment: sandbox başlığını taşır

#Kısaca kimlik doğrulama

1. Sahip veya yönetici olarak panelde “Callback ve API” altında ihtiyacın olan kapsamlarla bir API anahtarı oluştur (Creator Pro’dan itibaren)
2. Anahtar kimliğini ve anahtar gizli değerini POST /v1/token ile bir erişim token’ına dönüştür
3. Token’ı her istekte Authorization: Bearer … başlığında gönder
4. 15 dakika sonra yeni bir token al

Tüm ayrıntılar API anahtarları ve token’lar bölümünde, izinler Kapsamlar bölümünde.

#İstekler ve yanıtlar

Biçim

İstekler ve yanıtlar UTF-8’de JSON’dur. Dosya yüklemeleri ayrıca multipart/form-data kullanır.

Content-Type

Gövdesi olan her istekte Content-Type: application/json başlığını gönder. Başka her tür 400 bad_request ile reddedilir – bu başlık eksik olduğunda curl’ün -d için otomatik olarak ayarladığı tür dahil.

Bilinmeyen alanlar

Bir uç noktanın tanımadığı alanlar 422 validation_failed ile sonuçlanır. Yanıt bilinmeyen alanları belirtir.

Bozuk JSON

400 invalid_json ile sonuçlanır.

Boyut

Uç noktaya göre bir gövde en fazla 64 KB, 1 MB veya 2 MB, bir dosya yüklemesi ise 10 MB olabilir. Daha büyükse API 413 request_too_large ile yanıt verir. Tüm limitler Hız limitleri altında listeleniyor.

Listeler

items alanına sahip bir nesne olarak gelir, örneğin {"items":[…]}.

Oluşturma

HTTP 201 ve yeni kimlikle yanıt verir, örneğin {"id":123}.

Dönüş değeri olmayan işlemler

{"ok":true} ile yanıt verir.

Hatalar

Her zaman makine tarafından okunabilir bir kodla sabit bir biçime sahiptir. Bkz. Hata biçimi ve hata kodları.

#Sayfalama

Tek bir sayfalama düzeni yoktur. Listelerin çoğu küçüktür ve eksiksiz döner; yalnızca birkaç uç noktanın parametreleri vardır:

Kısa bağlantılarda sort için created_desc, created_asc, redirects_desc ve redirects_asc var; q slug, başlık ve hedef URL’de arar (en fazla 100 karakter, büyük/küçük harfe duyarsız). İstatistiklerde period 24h, 7d, 30d, 90d, this_month, last_month, last_30d ve custom değerlerini kabul eder; alternatif olarak from ve to gönderirsin. granularity hour veya day’dir.

#İstek kimliği ve dil

• Her yanıt X-Request-Id başlığını taşır – destek ekibiyle iletişime geçtiğinde bunu ekle
• Kendin bir X-Request-Id başlığı gönderirsen API onu kullanır
• message içindeki hata metni çalışma alanı sahibinin hesap dilindedir, aksi halde Accept-Language’i izler; error içindeki kod her zaman aynı kalır

#Tarayıcıdan mı çağırıyorsun?

Teknik olarak API tarayıcıdan yapılan çağrılara izin verir (CORS). Ancak bir anahtar gizli değeri asla ziyaretçi tarafında çalışan koda ait değildir – ne bir web sitesine ne de bir uygulamaya. API’yi her zaman kendi sunucundan çağır.

#Planlar

Plan başına API çağrısı kotası yoktur. Yalnızca dakika başına hız limitleri geçerlidir. Planının sayfa başına sayfa, bağlantı veya blok gibi içerik limitleri API üzerinden de paneldeki gibi geçerlidir. Bkz. Planların karşılaştırması.

#İlk çağrın

# Anahtarı bir token’la değiştir
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# Sayfaları listele (kapsam read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Bir bağlantı ekleyen, tasarımı değiştiren ve yayınlayan eksiksiz bir örnek Bir sayfayı API ile güncelle bölümünde.