Endüstriyel otomasyon sistemlerinde REST API'ler sadece veri taşıma kanalı değil; operasyonel karar sürecinin, uzaktan konfigürasyonun ve gerçek zamanlı izleme akışının temelidir. Bir üretim hattında veya proses kontrol sisteminde API davranışı, hata toleransı ve gecikme profili doğrudan üretim verimliliğini etkiler. Bu yazıda gerçek saha tecrübelerinden yola çıkarak REST API'lerin tanımı, geliştirilmesi, hataların tanılanması ve saha düzeltme yaklaşımlarını detaylandırıyorum.
Operasyonel risk, genellikle beklenmeyen gecikmeler (latency) ve artan hata oranlarıyla kendini gösterir. Bir hattın kontrol paneline zamanında ulaşamayan telemetri, %5-10 arası üretim kaybına yol açabilecek karar gecikmeleri doğurabilir. Bu nedenle API tasarımında yalnızca işlevsellik değil; gecikme, hata oranı ve throughput (TPS/RPS) hedefleri net olarak belirlenmelidir.
Teknik kapsam: bu yazı API sözleşmesi (contract-first), performans hedefleri, güvenlik doğrulama, sürüm yönetimi ve saha testleri gibi bileşenleri kapsar. Her bölümde en az iki ölçülebilir parametre, bir ölçüm yöntemi ve saha davranış örneği yer alır. Ölçümlerde ms, TPS, yüzde ve RPS sıkça kullanılacaktır.
Unutmayın: API tasarımı teorik bir aktivite değildir; sahada ölçülür, test edilir ve sonuçlarla düzeltilir. Pratikte uygulanmayan tasarım, risk yönetimi eksikliği demektir.
REST API, kaynak temelli HTTP etkileşimleriyle sistemler arası veri alışverişini tanımlar. Temel olarak URI, yöntem (GET/POST/PUT/DELETE), durum kodu ve taşıyıcı yükten (payload) oluşur. Endüstride REST API, cihaz telemetrisinin, konfigürasyon komutlarının ve işlem sonuçlarının taşınmasında kullanılır.
Ölçülebilir sınırlar: tipik SLA hedefleri 95. yüzdelik gecikmenin 200 ms altında olması, hata oranının %0.5'in altında kalması ve sistemin en az 500 TPS (işlem/saniye) yükünü 5 dakika süreyle sürdürebilmesidir. Bu sınırlar, üretim hattı kontrolü için referans örnektir ve uygulamaya göre değişir. Örneğin bir enerji santralinde gecikme hedefi 50 ms, TPS beklentisi ise 2000 TPS olabilir.
Sistem bileşen ilişkisi: API gateway, kimlik doğrulama servisi, uygulama sunucuları, veri tabanı ve izleme altyapısı birbirine zincirlenmiş bileşenlerdir. Bir bileşendeki kaynak tüketimi (CPU% veya I/O gecikmesi) tüm zinciri etkiler; bu yüzden end-to-end ölçümler şarttır.
REST API: HTTP tabanlı kaynak erişim arayüzüdür; belirlenen SLA'ler ölçülebilir metriklerle desteklenmelidir.
"API sözleşmesi" sadece JSON şema değil; gecikme hedefleri, hata sınıfları ve yeniden deneme politikalarını da içermelidir. Bu bakış açısı, saha uygulamalarında hataların tekrarlanma sıklığını azaltır.
Problem: Uzun TCP el sıkışmaları, paket kaybı veya VPN tüneli üzerinden geçen trafik nedeniyle uçtan uca gecikme artar. Bu durum komutların zamanında uygulanmamasına ve kontrol döngülerinin bozulmasına neden olur.
Teknik detay: 95. yüzdelik latency (p95) ve 99. yüzdelik latency (p99) sıklıkla kontrol edilmelidir. Örnek hedef: p95 < 200 ms, p99 < 500 ms. Ayrıca TCP retransmit oranı %0.1’in üzerinde ise sorun var demektir.
Ölçülebilir parametreler: p95 latency (ms), paket yeniden iletim oranı (%)
Analiz yöntemi: packet capture + histogram; p95/p99 histogramı ile uçtan uca gecikme dağılımı çıkarılır.
Problem: JWT süresi,_CLOCK drift veya token revocation sorunları yetkilendirme hatalarına yol açar. Bu hata tipi sahada erişim reddine neden olur ve elle müdahale gerektirir.
Teknik detay: token doğrulama süreleri, doğrulama başarısızlık oranı ve kimlik doğrulama isteği gecikmesi kritik metriklerdir. Hedef örneği: auth isteği < 50 ms, başarısız auth oranı < %0.2.
Ölçülebilir parametreler: auth latency (ms), auth failure rate (%)
Analiz yöntemi: log korelasyonu — uygulama logları ile auth sunucusu loglarını karşılaştırın.
Problem: API şeması değişiklikleri nedeniyle cihazlar veya uygulamalar beklenmedik hatalar verir. Sürüm uyuşmazlığı veri uyumsuzluğuna, işlem kaybına sebep olabilir.
Teknik detay: API sürüm uyumluluğu yüzdesi, schema validation hata oranı ve geri uyumluluk testi başarı oranı ölçülmelidir. Hedef örneği: prod’ta %100 backward compatibility test geçişi, schema error rate < %0.1.
Ölçülebilir parametreler: schema error rate (%), backward compatibility test pass rate (%)
Analiz yöntemi: automated contract testing + histogram ile schema mismatch frekansı ölçümü.
Problem: Ani yük artışları (ör. periyodik raporlama, gece batch'leri) node başına CPU% ve bellek tüketimini artırır; yatay/vertical scaling gecikmeleri tahmin edilemeyen hata oranlarına yol açar.
Teknik detay: hedefler arasında 99. yüzdelik işlem gecikmesi, CPU% (95. percentil) ve RPS/TPS sınırlayıcılar olmalıdır. Örnek hedef: node CPU% < 70% (sürdürülebilir), throughput 2000 RPS toplam.
Ölçülebilir parametreler: node CPU% (95th), throughput (RPS/TPS)
Analiz yöntemi: load test + histogram + resource utilization grafikleri; yatay ölçeklendirme gecikmesini ölçün (saniye).
Aşağıdaki tablo, saha servis seviyelerini daraltmak için kullanılabilecek kısa bir kod tablosudur.
| Kod | Belirti | Olası Neden | Ölçüm |
|---|---|---|---|
| ERR01 | Yüksek p95 latency | Ağ gecikmesi / kötü routing | p95 histogram (ms) |
| ERR02 | Auth hataları | Token süresi / IdP gecikmesi | Auth failure rate (%) |
| ERR03 | Schema mismatch | Sürüm uyuşmazlığı | Schema error rate (%) |
Sorun tanılama sürecinde, fiziksel ağdan uygulama katmanına doğru ilerleyerek daraltma yapmak en verimli yöntemdir. Aşağıda sahada uygulayacağınız sıralı yaklaşım yer alır.
Bir üretim tesisinde gece vardiyasında API çağrılarının yavaşlaması bildirildi. İlk yanlış varsayım, uygulama sunucusunda bellek sızıntısıydı. Ancak p95 latency histogramı ve packet capture sonuçları, gece saatinde çalışan yedekleme servisi nedeniyle ağ bant genişliğinin %60 kullanılmasından kaynaklandığını gösterdi.
Analiz sonucunda kök neden: backup job’un aynı VLAN içinde yoğun paket gönderimi yapması ve MTU ile fragmentation oluşması. Kalıcı çözüm açısından backup trafiğini farklı bir VLAN'a kaydırdık, QoS ile kontrol altına aldık ve p95 gecikme %37 azaldı; hata oranı %2.4'ten %0.4'e düştü. Bu uygulama sahada 24 saat içinde gözlemlenebilir iyileşme sağladı.
Uzun ömürlü API tasarımı, ölçüm kültürüyle birlikte gelir. İzleme verileri düzenli olarak analiz edilmeli ve KPI sapmaları otomatik olarak uyarı üretmelidir.
Ölçülmeyeni yönetemezsiniz; API performans yönetimi, sürekli ölçüm ve sahadan gelen verilerle güçlenir.
REST API tasarımı ve saha uygulaması çok katmanlı bir yaklaşıma ihtiyaç duyar: ağ, kimlik doğrulama, şema yönetimi ve ölçeklenebilirlik birbirine bağlıdır. Her katmanda ölçülebilir hedefler belirleyin ve bu metrikleri izleme kültürünüzün merkezine koyun.
KB Yazılım yaklaşımı, contract-first, sahada testlendirilmiş canary stratejileri ve ölçülebilir SLA hedefleriyle farklılaşır; özellikle üretim ve enerji sektörlerinde uyguladığımız projelerde p95 gecikme ve hata oranlarında karşılaştırmalı %30–50 iyileşme sağladık. Saha içgörülerimiz, yerel ağ topolojilerinin (örn. fabrika içi VLAN'lar ve VPN tünelleri) Türkiye'deki tesislerde performansı belirgin şekilde etkilediğini gösteriyor.
Ölçüm ve izleme kültürüyle birlikte uygulanan iyi tanımlanmış API sözleşmeleri, saha operasyonel risklerini azaltır ve hata tekrarlanma oranını düşürür. KB Yazılım olarak bu yaklaşımları proje bazında uygulamaya alıyoruz ve birlikte çalışmaya açığız.