Geliştirici belgeleri

uhm.co API'si: diğer yazılımlardan bağlantı oluşturma ve yönetme, her biri için tıklama istatistikleriyle birlikte.

Kimlik doğrulama

Bir API anahtarı, Pro ve üzeri planlarda kullanılabilen kontrol panelinin API anahtarları ekranından oluşturulur. Her anahtar, oluşturulduğunda kendisine verilen yetkileri taşır. Bir istek, anahtarı taşıyıcı kimlik bilgisi olarak içeren bir Authorization başlığıyla kimlik doğrular.

Authorization: Bearer uhm_live_...

Yetkiler

links:read bağlantıları listeler ve okur.
links:write bağlantı oluşturur, günceller ve siler.
analytics:read tıklama istatistiklerini okur.

/v1/me hiçbir yetki gerektirmez. Bir anahtarın kendini tanımlayamaması, bir yanlış yapılandırmanın bir entegrasyonun kendi ayarlar ekranından teşhis edilmesini imkânsız kılar.

Tasarım gereği yalnızca sunucu tarafında

Bu API, kasıtlı olarak hiçbir CORS başlığı göndermez ve bu bildirilmesi gereken bir eksiklik değildir. Bir anahtar taşıyıcı bir kimlik bilgisidir: onu elinde bulunduran, tüm çalışma alanı için bağlantı oluşturabilir ve analitik verilerini okuyabilir. Bir anahtarın tarayıcı JavaScript'ine yerleştirilmesi, sayfayı yükleyen her ziyaretçiye o anahtarı yayınlamak anlamına gelir. Eksik CORS başlıkları, bu API'nin bir tarayıcı tarafından çağrılmasını yalnızca tavsiye etmek yerine fiilen imkânsız kılar. Her istek bir sunucudan gönderilmelidir, hiçbir zaman bir ziyaretçinin tarayıcısında çalışan bir koddan değil.

Yinelemeden yayınlama

reference, çağıran taraf tarafından verilen, en fazla 255 karakterlik, bağlantının çağıranın kendi tarafında neyi temsil ettiğini adlandıran bir tanımlayıcıdır; örneğin bir CMS yazısı. Çalışma alanında zaten var olan bir reference ile bağlantı oluşturmak, 200 durum koduyla kayıtlı bağlantıyı döndürür ve yeni bir şey oluşturmaz. Gerçek bir oluşturma 201 döner; böylece bir entegrasyon ikisini zaman damgalarını karşılaştırmadan ayırt edebilir.

Örnek: bir CMS'in yazı yayınlaması

Bir site 142 numaralı yazıyı yayınlar. Eklenti, reference değeri "wp:example-com:142" ve destination_url olarak yazının adresiyle POST /v1/links isteği gönderir. Bu reference için henüz bir bağlantı olmadığından yeni bir bağlantı oluşturulur ve yanıt 201 olur.
Yazar, yazıyı düzenleyip yeniden yayınlar. Eklenti aynı isteği, aynı reference ve aynı hedefle tekrar gönderir. Bu reference için zaten bir bağlantı var olduğundan yeni bir şey oluşturulmaz; yanıt 200 olur ve aynı bağlantıyı, aynı id ile döndürür.
Sitenin kalıcı bağlantı yapısı değişir ve yazı artık farklı bir adreste yer alır. Eklenti, yeni destination_url değeriyle PATCH /v1/links/{id} isteği gönderir. reference bir PATCH ile değiştirilemez: eklentinin daha önce oluşturduğu bağlantıyı tanımasını sağlayan alan budur; bir düzenlemenin bunu taşımasına izin vermek, bir isteğin başka bir bağlantıyı sessizce sahipsiz bırakmasına yol açardı.

Uç noktalar

/v1/me dışındaki her uç nokta, anahtarın ait olduğu çalışma alanıyla sınırlıdır. Var olan ama başka bir çalışma alanına ait bir bağlantı, hiç var olmayan bir bağlantıyla aynı şekilde yanıtlanır.

Metot	Yol	Yetki	Açıklama
GET	`/v1/me`	yok	Anahtar, çalışma alanı ve kalan hak.
GET	`/v1/links`	`links:read`	Bağlantıları sayfalı biçimde listeler.
POST	`/v1/links`	`links:write`	Bir bağlantı oluşturur, ya da bir reference için var olan bağlantıyı döndürür.
GET	`/v1/links/{id}`	`links:read`	Tek bir bağlantıyı okur.
PATCH	`/v1/links/{id}`	`links:write`	Bir bağlantıyı günceller.
DELETE	`/v1/links/{id}`	`links:write`	Bir bağlantıyı siler.
GET	`/v1/links/{id}/stats`	`analytics:read`	Tek bir bağlantı için tıklama istatistikleri.

Sorgu parametreleri: GET /v1/links

page_size: Sayfa boyutu. Varsayılan 50, en fazla 200.
cursor: Önceki sayfanın next_cursor değerinden alınan, anlamı belirtilmemiş bir sayfalama imleci. İlk sayfa için boş bırakılır.
reference: Sayfayı yalnızca bu reference değerini taşıyan bağlantılarla sınırlar.

Sorgu parametreleri: GET /v1/links/{id}/stats

days: Geriye dönük pencere, tam gün olarak. Varsayılan 30, en fazla 1095.

Hatalar

Her hata yanıtı aynı biçimdedir: { "error": { "code", "message", "docs_url" } }. Bir entegrasyonun karar vermesi gereken alan code'dur. message, çalışma alanının kendi dilinden bağımsız olarak yalnızca İngilizce yazılan, geliştiriciye yönelik bir hata ayıklama metnidir: bir müşterinin ekranda okuduğu bir metin değil, bir geliştiricinin sunucu kaydında okuduğu bir metindir ve bu bilinçli bir tercihtir, bir eksiklik değildir. Kontrol paneli ve bu sayfa, müşteriye görünen her şey gibi, iki dilde de eksiksizdir. docs_url, aşağıdaki ilgili satıra yönlendirir.

Kod	Durum	Anlamı
`invalid_request`	400	Bir istek alanı eksik veya hatalı biçimde gönderilmiştir.
`invalid_slug`	400	İstenen kısa ad izin verilmeyen karakterler içeriyor.
`destination_rejected`	400	Hedef URL, bağlantı oluşturulmadan önce reddedildi. Neden, reason alanında belirtilir: kendine referans, IP adresi biçiminde bir host, zincirleme bir kısaltma servisi ve gerçek bir hedefi göstermesi son derece düşük ihtimalli birkaç başka örüntü.
`unauthenticated`	401	Anahtar eksik, tanınmıyor, iptal edilmiş ya da süresi dolmuş.
`quota_exceeded`	402	Aylık bağlantı hakkı tükenmiş ve kalan kredi yok. Daha önce oluşturulan bağlantılar yönlendirmeye devam eder; bu hata yalnızca yeni oluşturmayı engeller.
`insufficient_scope`	403	Anahtar, bu uç noktanın gerektirdiği yetkiyi taşımıyor. Gerekli yetki required_scope alanında belirtilir.
`feature_not_available`	403	Kullanılan alan (özel kısa ad, şifre veya son kullanma tarihi) çalışma alanının mevcut planına dahil değil. Hangisi olduğu feature alanında belirtilir.
`api_not_included`	403	Çalışma alanının planı API erişimini hiç içermiyor. Gerekli plan required_plan alanında belirtilir.
`workspace_banned`	403	Çalışma alanının bağlantı oluşturması ve düzenlemesi engellenmiştir.
`trial_expired`	403	Çalışma alanının deneme süresi sona erdi ve etkin bir plan yok.
`domain_not_verified`	403	domain_id, doğrulaması henüz tamamlanmamış bir alan adını gösteriyor.
`not_found`	404	Böyle bir bağlantı yok, ya da bağlantı başka bir çalışma alanına ait. domain_id, çalışma alanının kendi alan adlarından birini göstermediğinde de aynı hata döner.
`slug_taken`	409	Bu kısa ad zaten kullanımda.
`slug_reserved`	409	Bu kısa ad ayrılmış olduğundan kullanılamaz.
`destination_unsafe`	422	Hedef, güvenlik taramasında işaretlendi.
`rate_limited`	429	Geçerli pencerede çok fazla istek gönderildi. Kaç saniye beklenmesi gerektiği Retry-After alanında belirtilir.
`internal_error`	500	İstek bizim tarafımızda tamamlanamadı.
`api_not_configured`	503	API bu dağıtımda yapılandırılmamış.

İstek sınırları

Sınırlar anahtar başına, dakika başına uygulanır; okuma ve yazma istekleri ayrı sayılır. Her yanıt X-RateLimit-Limit ve X-RateLimit-Remaining taşır; 429 yanıtları ayrıca Retry-After taşır.

Plan	Okuma / dk	Yazma / dk
Pro	600	60
Business	3000	300

Makine tarafından okunabilir açıklama

API'nin tamamı, yukarıda açıklanan uç noktalardan üretilen OpenAPI 3.1 biçiminde tanımlanmıştır.

openapi.json dosyasını görüntüleyin