- Katılım
- 21 May 2023
- Mesajlar
- 753
- Tepki
- 17
- Puan
- 18
Muhasebe programınız siparişleri görmüyorsa, kargo firması numaraları geri yazamıyorsa aradaki eksik parçanın adı entegrasyon oluyor. Kelime kulağa idari geliyor ama karşılığı teknik: iki yazılımın birbirinin verisini hangi kurallara göre alıp vereceğinin baştan yazılması.
Aşağıda entegrasyonun neye dayandığını, tarafların anlaştığı belgenin ne içerdiğini, isteklerin hangi sınıflara ayrıldığını ve bağlantı koptuğunda hangi çağrının tekrarlanabileceğini standart belgelerine bakarak topluyoruz.
Bağlantının dayandığı şey
Entegrasyonun temeli veri değil, tanım. İki taraf hangi adresten hangi biçimde veri isteneceğini bilmezse bağlantı her sürümde yeniden kurulmak zorunda kalıyor.
Bu tanımı yazılı hâle getiren biçimlerden biri OpenAPI Belirtimi. Belgenin kendi tarifine göre ortaya koyduğu şey, HTTP arayüzlerini betimleyen ve hangi dille yazıldığından bağımsız çalışan standart bir arayüz tanımı.
İki yazılımın karşılıklı çağrı düzenini API yazımızda genel hatlarıyla anlatmıştık; buradaki konu o düzenin yazıya dökülmüş hâli.
Vaadi de yazılı: uygun biçimde tanımlandığında tüketici tarafı, kaynak koda, ek belgeye ya da ağ trafiğini incelemeye ihtiyaç duymadan uzak hizmetin yeteneklerini anlayabiliyor ve asgari uygulama mantığıyla onunla etkileşebiliyor.
- Ne tanımlıyor: HTTP arayüzünü, dilden bağımsız biçimde.
- Kime hitap ediyor: Hem insana hem makineye.
- Ne kazandırıyor: Hizmeti çağırırken tahmin yürütmeyi ortadan kaldırıyor.
Belge neyi içermek zorunda?
Belirtim, tanım dosyasını "kendi başına yeten ya da bileşik bir kaynak" olarak tarifliyor: bir arayüzü ya da arayüzün ögelerini tanımlayan veya betimleyen bir kaynak.
Zorunlu asgari de yazılı: belgenin en az bir yol alanı, bir bileşenler alanı ya da bir webhook alanı içermesi gerekiyor.
Biçim tarafında iki seçenek var. Belirtime uyan bir tanım dosyası aslında bir JSON nesnesi ve JSON ya da YAML biçiminde temsil edilebiliyor.
Bir uyarı da düşülmüş: arayüz YAML ya da JSON ile tanımlanmış olsa bile istek ve yanıt gövdelerinin JSON veya YAML olması zorunlu değil.
Belge iki noktada dışarıya da bağlanıyor. Ortam türü tanımlarının RFC 6838 ile uyumlu olması gerektiğini söylüyor ve örnek olarak text/plain; charset=utf-8 ile application/json gibi değerleri sayıyor.
Durum kodları içinse kendi listesini kurmuyor: yürütülen işlemin durumunu göstermek için kullanılan kodların IANA kayıt defterinde listelendiğini belirtiyor.
Adres kalıpları ve sürüm
Yol şablonlaması, adresin değişken kısmını süslü parantezle işaretleme yöntemi olarak tanımlanıyor: yoldaki her şablon ifadesi, karşılığında bir yol parametresine denk gelmek zorunda.
Sürüm numarası da rastgele değil. Belirtim ana.ikincil.yama düzenini kullanıyor; ana ve ikincil kısım özellik kümesini gösteriyor, yama sürümü ise özellik kümesini değil belgedeki hataları ve açıklamaları ele alıyor.
Araç tarafına düşen sonuç şu: 3.1 destekleyen bir araç bütün 3.1.* sürümleriyle uyumlu olmalı ve yama numarasını dikkate almamalı.
Sürüm numaralarının genel mantığını sürüm yazımızda ayrıca ele almıştık; buradaki düzen aynı fikrin belge tarafındaki uygulaması.
İstekler hangi sınıflara ayrılıyor?
Veri alışverişinin ikinci yarısı isteğin kendisi. RFC 9110 istek metotlarını iki özelliğe göre ayırıyor.
Birincisi güvenli olma: tanımlı anlamı esas olarak salt okunur olan metotlar güvenli sayılıyor; istemci sunucuda durum değişikliği talep etmiyor ve beklemiyor. Belge GET, HEAD, OPTIONS ve TRACE metotlarını güvenli olarak tanımlıyor.
İkincisi etkisizlik: aynı isteğin birden çok kez gönderilmesinin sunucudaki amaçlanan etkisi tek bir istekle aynıysa metot etkisiz sayılıyor. Belirtimde PUT, DELETE ve güvenli metotlar bu sınıfta.
Püf nokta' Alıntı:
Bağlantı koptuğunda ne yapılır?
Ayrımın pratikteki karşılığı yeniden deneme. Belge şunu söylüyor: iletişim hatası, istemci yanıtı okuyamadan oluşursa etkisiz istek otomatik olarak tekrarlanabiliyor.
Örneği de veriliyor: PUT isteği gönderildikten sonra bağlantı yanıt alınmadan kapanırsa istemci yeni bağlantı kurup isteği yineleyebilir, çünkü etkinin aynı kalacağını biliyor.
Ters yönde bir sınır da konuyor: istemci, etkisiz olmayan bir metodu, isteğin gerçekten etkisiz olduğunu ya da özgün isteğin hiç uygulanmadığını bilmedikçe otomatik olarak tekrarlamamalı. Vekil sunucular içinse kural daha katı: etkisiz olmayan istekleri otomatik olarak yeniden denememeli.
Bu, webhook yazımızda anlattığımız yeniden deneme kurgusunun neden dikkatli tasarlanması gerektiğini de açıklıyor.
Sık Sorulan Sorular
Entegrasyon ne demek?
İki yazılımın veri alışverişini, önceden tanımlanmış bir arayüz üzerinden yapması; tanım tarafların ortak sözleşmesi işlevi görüyor.
OpenAPI belgesi ne işe yarıyor?
HTTP arayüzünü dilden bağımsız biçimde tanımlıyor; karşı taraf kaynak koda bakmadan hizmeti anlayabiliyor.
Belgede en az ne bulunmalı?
En az bir yol alanı, bir bileşenler alanı ya da bir webhook alanı.
Güvenli metot hangisi?
Belirtimde GET, HEAD, OPTIONS ve TRACE; anlamları salt okunur olduğu için bu sınıfta.
Hangi istek tekrarlanabilir?
Etkisiz olanlar: PUT, DELETE ve güvenli metotlar. Etkisiz olmayan istekler bilinmeden yinelenmemeli.
Özetle
Entegrasyon, iki sistemin ortak bir tanım üzerinde anlaşması demek. Tanım tarafında OpenAPI belgesi adresleri, parametreleri ve biçimi makine okunur hâle getiriyor; istek tarafında ise metodun güvenli mi etkisiz mi olduğu, bağlantı koptuğunda çağrının tekrar edilip edilemeyeceğini belirliyor. İki taraf da yazılı olduğunda bağlantı, karşı ekibin sürüm çıkmasına dayanıklı hâle geliyor.
Bağlandığınız servisin tanım dosyası elinizde mi, yoksa alanları örnek yanıtlardan mı çıkarıyorsunuz?
Güncelleme: 4 Eylül 2026. OpenAPI Specification 3.1.0 ve RFC 9110 (HTTP Semantics) kontrol edildi.
Dijital Dünyanıza Yön Veren Pusula
