Cevap.

Tarihi olarak, sistemler arası arayüzlerin tanımlanması mimarlara ve entegratörlere aitti ve genellikle veri yapısını içeren e-posta alışverişine indirgeniyordu. SOA döneminde ve özellikle mikro hizmet mimarisi döneminde, sistem analistinin entegrasyon sözleşmelerinin formelleştirilmesi ve desteklenmesi konusunda rolü büyük ölçüde arttı.

Problem

Hatalı, eksik veya güncel olmayan API arayüz tanımları, servislerin uyumsuzluğu, hataların artması, sistemin genel çalışma düzenini bozacak değişikliklerin yapılamaması gibi sorunların kaynağıdır. Çoklu servis projelerinde entegrasyon noktalarının sayısı onlarca veya yüzlerceyi bulmaktadır.

Çözüm

Sistem analisti modern uygulamaları kullanır:

REST için OpenAPI/Swagger gibi araçlar, gRPC protokolleri, SOAP için WSDL/XSD aracılığıyla sözleşmelerin formelleştirilmesi;
Tipik çağrı senaryoları ve hata durumlarının tanımlanması;
Gerçek zamanlı veri alışverişi için olay şemalarının (event-driven model) geliştirilmesi;
Güncel belgelerin tutulması ve sözleşmelerin otomatik üretilmesi;
Tüm etkilenen servislerin sahipleri ile değişikliklerin onaylanması.

Önemli bir unsur, sözleşmelerin doğru versiyonlarının tutulması ve değişikliklerin izlenmesidir, ayrıca etkileşimlerin doğrulanması için test senaryolarının entegrasyonudur.

Anahtar özellikler:

Makine tarafından okunabilir standartların (OpenAPI/YAML) kullanımı.
Tüm kullanım senaryoları ve hataların dikkate alınması.
Farklı servis takımları arasında düzenli iletişim.

Kandırmaca Sorular.

Analistin, API gereksinimlerini yalnızca müşteri ve iç geliştiricilerden toplaması gerekir mi?

Hayır, tüm entegre takımları dahil etmek, dış ortakların gereksinimlerini dikkate almak önemlidir, böylece boşluklar veya uyumsuzlukları önleyebilirsiniz.

API'leri yalnızca sistemin teslimat aşamasında belgelemek mümkün mü?

Hayır, API spesifikasyonu gerçekleştirilmeden önce oluşturulmalı ve onaylanmalıdır, aksi takdirde her aşamada geriye dönük uyumluluk bozulacaktır.

OpenAPI spesifikasyonu, tüm değişim durumları için yeterli bir belge midir?

Hayır, OpenAPI yapıları tanımlar, ancak etkileşim senaryolarını (örneğin, çağrı sırası, olay sırası, iş hataları) analistin kullanıcı belgelerinde ayrıntılı bir şekilde belirtmesi gerekir.

Tipik Hatalar ve Antipatternler

Güncel olmadan ya da "insan diliyle" tanım verirken spesifikasyonu vermek.
Hata işleme, örtük senaryoları belirtmemek.
Versiyon kontrolünün ve değişiklik izleme eksikliği.

Hayattan Bir Örnek

Olumsuz Durum: Lojistik sistemi, dış taşıyıcılarla entegre oldu. Sözleşme yalnızca "kelimelerle" tanımlandı. Değişikliklerin yürürlüğe girmesiyle birlikte yaygın entegrasyon hataları ve gecikmeler meydana geldi.

Artılar:

Başlangıçta minimum iş gücü gereksinimi

Eksiler:

Yaygın arızalar
Acil düzeltmeler
Olumsuz itibar

Olumlu Durum: Analist, hata/başarılı senaryolarla birlikte OpenAPI'yi oluşturdu, versiyonlamayı onayladı ve tüm takımlardan geri bildirim topladı.