Mikro Api Response Modelleri
Mikro API’de API Key neden önemlidir?
API Key, uygulamanızın API servisine yaptığı isteğin tanınmasına yardımcı olan temel kimlik doğrulama bilgilerinden biridir. İstek gövdesinde gönderilen API Key ile Mikro tarafında tanımlı API Key birbiriyle uyuşmadığında servis isteği geçerli kabul etmez. Mikro API dokümantasyonunda bu durum, 401 durum koduna sahip “Hatalı Giriş Yanıtı (Geçersiz ApiKey)” modeliyle açıklanmaktadır.
Bu hata, çoğu zaman API servisinin çalışmadığı anlamına gelmez. Daha yaygın senaryo, bağlantının API’ye ulaştığı ancak gönderilen kimlik doğrulama bilgisinin doğrulanamadığı durumdur. Bu nedenle hata incelemesine yalnızca ağ bağlantısından değil, istek içindeki kimlik doğrulama alanlarından başlamak gerekir.
401 ErrorResponse modeli ne anlatır?
Mikro API’nin ilgili yanıt modelinde hata, ErrorResponse adıyla ve 401 model numarasıyla gösterilir. Yanıtın içinde result adlı bir dizi bulunur. Bu dizinin ilk elemanında durum kodu, veri alanı, hata mesajı ve hatanın oluştuğunu belirten boolean değer yer alır
|
Alan
|
Veri tipi
|
Anlamı
|
|
result
|
Array
|
Yanıt ve hata ayrıntılarını içeren dizi
|
|
result[0].StatusCode
|
Integer
|
HTTP durum kodu; bu modelde örnek değer 401
|
|
result[0].Data
|
Null
|
Hata durumunda veri dönmediğini gösterir
|
|
result[0].ErrorMessage
|
String
|
Hatanın açıklamasını içerir
|
|
result[0].IsError
|
Boolean
|
Hata oluştuğunu belirtir; örnek modelde değer true’dur
|
Burada dikkat edilmesi gereken nokta, Data alanının null dönmesidir. Bu, isteğin beklenen iş verisini üretmediğini gösterir.
Uygulamanız, yalnızca HTTP durum kodunu değil, yanıt gövdesindeki IsError ve ErrorMessage alanlarını da kontrol etmelidir.
Örnek hata yanıtı
Dokümantasyonda verilen örnek yapı aşağıdaki gibidir:
{
“result”: [
{
“StatusCode”: 401,
“Data”: null,
“ErrorMessage”: “connection error – Geçersiz ApiKey!”,
“IsError”: true
}
]
}
Bu yanıtı uygulama tarafında okurken beklenen akış şöyledir: Önce HTTP yanıtının 401 olup olmadığı kontrol edilir. Ardından result dizisinin boş olup olmadığına bakılır. Dizi doluysa result[0].IsError değeri incelenir ve kullanıcıya ya da log sistemine ErrorMessage alanındaki açıklama aktarılır. Üretim ortamında API Key’in kendisi hata mesajına veya log kaydına yazılmamalıdır.
Geçersiz API Key hatasında hangi kontroller yapılmalı?
API Key değerini kontrol edin
İlk adımda uygulamanızın gönderdiği API Key’in eksiksiz ve doğru ortam için tanımlı olduğundan emin olun. Kopyalama sırasında başta veya sonda boşluk kalması, farklı bir test anahtarının canlı ortamda kullanılması ya da anahtarın yanlış JSON alanına yazılması doğrulama hatasına yol açabilir.
İstek gövdesini inceleyin
API Key’in gönderildiği alan adı, kullanılan endpoint’in beklediği yapıyla aynı olmalıdır. JSON içinde alan adının yanlış yazılması, değerin string yerine farklı bir türde gönderilmesi veya istek gövdesinin beklenen üst nesne içinde bulunmaması hataya neden olabilir. Geliştirme aşamasında isteği Postman gibi bir istemciyle ve uygulamanızın gerçek isteğiyle karşılaştırmak yararlı olabilir.
Firma ve çalışma ortamını doğrulayın
API Key doğru olsa bile test ve üretim ortamlarının birbirine karıştırılması sorun çıkarabilir. Firma kodu, çalışma yılı, servis adresi ve port bilgisi gibi bağlantı parametrelerinin aynı ortama ait olduğundan emin olun. Bu değerleri web sayfanızda veya herkese açık kod örneklerinde gerçek bilgilerle paylaşmayın.
Servis ve port ayarlarını kontrol edin
Kimlik doğrulama hatası doğrudan port sorunu değildir; ancak yanlış servis adresi veya yanlış yapılandırma, beklediğiniz API ortamına ulaşamamanıza neden olabilir. Bu nedenle API servisinin çalışır durumda olması, kullanılan adresin doğru olması ve ağ yönlendirmelerinin sistem yöneticisi tarafından doğrulanması gerekir. Port bilgileri Mikro sürümüne ve kurulum yapılandırmasına bağlı olarak teyit edilmelidir.
API Key lisansını doğrulayın
Anahtarın ilgili ürün, firma veya ortam için yetkili olup olmadığını kontrol edin. Dokümantasyonda API Key lisanslamasının kullanım modeline göre otomatik veya manuel olarak verilebildiği belirtilmektedir. Anahtarın geçerliliği konusunda kesin bilgi için yetkili lisans veya entegrasyon kanalınızdan doğrulama isteyin.
Uygulama tarafında hata yönetimi nasıl tasarlanmalı?
İyi bir hata yönetimi, kullanıcıya yalnızca “Bir hata oluştu” mesajı göstermekten daha fazlasını yapar. Uygulama, teknik ayrıntıyı güvenli biçimde loglamalı; kullanıcıya ise API Key’in kontrol edilmesi gerektiğini belirten sade bir açıklama sunmalıdır.
Örnek bir sözde kod akışı şu şekilde tasarlanabilir:
Plain Text
İsteği gönder Eğer HTTP durum kodu 401 ise: Yanıt gövdesini güvenli biçimde oku result dizisini kontrol et ErrorMessage alanını teknik loga yaz Kullanıcıya “API kimlik doğrulaması başarısız oldu” mesajını göster API Key değerini loglama Aksi durumda: Başarı veya ilgili diğer hata senaryosunu işle
Uygulamanızın kullandığı yazılım diline göre bu akış JavaScript, C#, PHP, Python veya başka bir dilde uygulanabilir. Buradaki önemli tasarım ilkesi, hatanın yakalanması kadar gizli bilgilerin korunmasıdır.
Güvenli API Key kullanımı için öneriler
API Key’i frontend JavaScript koduna, herkese açık Git deposuna, ekran görüntüsüne veya blog yazısındaki gerçek örneklere yerleştirmeyin. Anahtarı sunucu tarafında, ortam değişkeni veya güvenli bir gizli bilgi yönetimi mekanizmasıyla saklayın. Log kayıtlarında API Key’i maskeleyin ve destek talebi oluştururken anahtarın tamamını göndermeyin.
Test ve üretim anahtarlarını birbirinden ayırmak, erişim yetkilerini sınırlamak ve anahtar değişikliği gerektiğinde yenileme prosedürü oluşturmak da entegrasyon güvenliğini artırır. Teknik ekipler ayrıca hata mesajlarını izleyen, ancak hassas değerleri kaydetmeyen bir loglama standardı belirlemelidir.
Sık sorulan sorular
401 hatası her zaman API Key’in yanlış olduğunu mu gösterir?
Bu yazının dayandığı Mikro API yanıt modelinde 401, geçersiz API Key senaryosu için kullanılmaktadır. Yine de uygulamanızdaki diğer kimlik doğrulama alanlarını, ortam bilgilerini ve güncel endpoint dokümantasyonunu birlikte kontrol etmelisiniz.
Data: null ne anlama gelir?
Hata yanıtında iş verisi dönmediğini gösterir. Bu nedenle uygulamanız Data alanını kullanmadan önce IsError ve HTTP durum kodunu kontrol etmelidir.
IsError: true nasıl ele alınmalı?
Bu değer, yanıt modelinde hata oluştuğunu belirtir. Uygulama, ErrorMessage alanını güvenli biçimde loglamalı ve son kullanıcıya teknik sırrı açığa çıkarmayan anlaşılır bir mesaj göstermelidir.
API Key’i destek ekibine gönderebilir miyim?
API Key’in tamamını göndermek yerine maskelenmiş biçimde paylaşın. Örneğin ABCD••••••7890 formatını kullanabilir, bağlantı adresi, parola ve firma bilgilerini de ayrıca gizleyebilirsiniz.
Sonuç
Mikro API’de geçersiz API Key hatasını doğru yorumlamak için yalnızca ekranda görünen hata mesajına bakmak yeterli değildir. 401 durum kodu, result dizisi, StatusCode, Data, ErrorMessage ve IsError alanları birlikte değerlendirilmelidir. Ardından API Key’in doğruluğu, istek gövdesi, ortam bilgileri, servis yapılandırması ve lisans durumu kontrollü biçimde incelenmelidir.
Bu yaklaşım, entegrasyon sorunlarını daha hızlı teşhis etmenize ve son kullanıcıya daha anlaşılır hata mesajları sunmanıza yardımcı olur. API yapılandırmanızda sürüm veya ortam değişikliği varsa, yayına almadan önce güncel Mikro API dokümantasyonunu esas alın.