01Sorun ve çözüm
API geliştirme işine kod yazarak değil, sözleşmeyi yazarak başlıyoruz. Hangi kaynağın kimlere açılacağı, hangi alanların döneceği, hataların nasıl bildirileceği ve servisin hangi sürüm kuralıyla değişeceği OpenAPI gibi makinece okunabilir bir belgede tanımlanır. Karşı taraftaki ekip bu belgeyle daha servis bitmeden geliştirmeye başlayabilir; siz de neyi kime açtığınızı tek yerden görürsünüz.
02Kimler için
API yazılımı hangi durumlarda gerekir
Aşağıdaki tablolardan biri size tanıdık geliyorsa veriye kontrollü bir kapı açmanın zamanı gelmiştir.
- Bayilerine ya da kurumsal alıcılarına anlık stok, fiyat ve sipariş durumu açmak isteyen distribütör ve üreticiler
- Web sitesinin yanına mobil uygulama ekleyecek ve iki arayüzü aynı servisten beslemek isteyen işletmeler
- Kendi ürününü başka yazılımlarla entegre edilebilir hâle getirmek isteyen SaaS girişimleri
- Yıllar önce yazılmış SOAP servislerini ya da dosya aktarımlarını modern bir arayüzle değiştirmek isteyen firmalar
- Muhasebe, depo ve satış sistemleri arasında elle veri taşıyan ve bu adımları otomatikleştirmek isteyen ekipler
03İhtiyaçlar
İyi tasarlanmış bir API'nin çözdüğü sorunlar
Servisi kullanacak geliştiricinin deneyimi, servisin kendisi kadar önemlidir.
- 01
Karşı tarafı bozmadan değişebilmek
Yeni bir alan eklemek mevcut entegrasyonları etkilememeli, kaldırılacak bir alan ise önceden duyurulmalıdır. Sürüm numaralandırma ve kullanımdan kaldırma takvimi bu yüzden ilk sürümde belirlenir.
- 02
Kimin neye eriştiğini bilmek
Her iş ortağına ayrı anahtar ya da istemci kimliği verilir; bir bayinin yalnızca kendi siparişlerini görmesi sunucu tarafında zorunlu tutulur. Anahtar sızdığında yalnızca o erişim iptal edilir.
- 03
Tekrarlanan isteklerde çift kayıt oluşmaması
Mobil ağda zaman aşımına uğrayan bir sipariş isteği yeniden gönderildiğinde ikinci sipariş açılmamalıdır. İstemcinin gönderdiği tekil işlem anahtarıyla aynı istek bir kez işlenir.
- 04
Anlaşılır hata mesajları
Yalnızca genel bir sunucu hatası dönen servis, destek hattını meşgul eder. Hangi alanın neden reddedildiğini standart bir yapıda bildiren hata yanıtları entegrasyon süresini kısaltır.
04Özellikler
API yazılımı kapsamında teslim ettiklerimiz
Çalışan uç noktaların yanında, servisi başkalarının kullanabilmesi için gereken parçaları da hazırlıyoruz.
- 01
Etkileşimli dokümantasyon
Uç noktalar, örnek istek ve yanıtlarla birlikte tarayıcıda denenebilir bir belge olarak yayınlanır. Belge, sözleşme dosyasıyla birlikte güncellenir ve servisin verdiği yanıtlar otomatik testlerle bu sözleşmeye karşı denetlenir; böylece belge ile servis arasında fark oluşmaz.
- 02
Test ortamı ve örnek veri
İş ortakları gerçek siparişe dokunmadan deneme yapabilsin diye ayrı bir test ortamı ve anlamlı örnek kayıtlar hazırlanır.
- 03
Webhook ile olay bildirimi
Sipariş kargoya verildiğinde ya da stok sıfırlandığında karşı tarafın sürekli sorgulaması yerine kayıtlı adresine imzalı bir bildirim gönderilir; başarısız gönderimler belirli aralıklarla yeniden denenir.
- 04
Kullanım sınırları ve kota
Her istemci için dakikalık istek sınırı tanımlanır; hatalı yazılmış bir döngünün bütün servisi yavaşlatması engellenir.
05Entegrasyonlar
API yazılımı projelerinde bağlandığımız sistemler
Yeni servis çoğu zaman var olan sistemlerin önüne konan bir katmandır.
- 01
ERP ve ön muhasebe
Örneğin Logo, Mikro, Netsis ya da SAP Business One gibi sistemlerdeki cari, stok ve fiyat bilgisi, bu sistemlerin kendi servisleri ya da veritabanı görünümleri üzerinden okunarak dışarıya güvenli biçimde açılır.
- 02
Pazaryerleri ve kargo
Trendyol, Hepsiburada gibi pazaryerlerinin satıcı servisleri ile Yurtiçi, Aras gibi kargo firmalarının gönderi servisleri tek bir iç arayüz arkasında toplanır.
- 03
Ödeme ve e-fatura
iyzico, PayTR ya da banka sanal POS servisleri ve özel entegratör üzerinden e-Fatura ile e-Arşiv gönderimi sipariş akışına bağlanır.
- 04
Kimlik sağlayıcılar
Kullanıcı adına çalışan istemciler için OAuth 2.0 ve OpenID Connect, sunucudan sunucuya bağlantılar için istemci kimlik bilgileri akışı kullanılır.
06Süreç
API yazılımı yaptırmak istiyorum: süreç nasıl işler?
Adım 01
Analiz
İş akışınızı, kullanıcılarınızı ve mevcut sistemlerinizi dinleriz; kapsamı, öncelikleri ve kabul ölçütlerini yazılı hâle getiririz.
Adım 02
Tasarım
Ekran akışlarını ve veri modelini çıkarırız. Arayüzü sizinle gözden geçirip onay almadan geliştirmeye geçmeyiz.
Adım 03
Geliştirme
Kısa döngülerle çalışırız; her döngü sonunda çalışan bir sürümü test ortamında görürsünüz.
Adım 04
Test
İşlevsel testler, entegrasyon testleri ve temel güvenlik kontrolleriyle hataları yayından önce yakalarız.
Adım 05
Yayın
Sunucu, alan adı, yedekleme ve izleme ayarlarını yaparak canlıya alırız; ekibinize kısa bir kullanım eğitimi veririz.
Adım 06
Bakım
İsterseniz bakım ve destek anlaşmasıyla güncellemeleri, izlemeyi ve yeni geliştirmeleri sürdürürüz.
07Teknoloji
Protokol seçimi, güvenlik ve izlenebilirlik
Dışarıya açılan servislerde çoğunlukla REST tercih ediyoruz; anlaşılır, önbelleğe alınabilir ve her dilde istemcisi var. Ekranların çok farklı veri kombinasyonları istediği durumlarda GraphQL, iç servisler arasında yüksek hacimli iletişimde gRPC değerlendirilir. Seçim, servisi kimin ve hangi araçla kullanacağına göre yapılır.
Devamını okuDaha az göster
Güvenlik denetiminde OWASP'ın API güvenliği listesindeki başlıkları, özellikle nesne düzeyinde yetki kontrolünü esas alıyoruz. Her isteğe bir korelasyon kimliği verilir; bir iş ortağı sorun bildirdiğinde isteğin hangi adımda takıldığı kayıtlardan bulunur. Yanıt süreleri ve hata oranları izlenir, eşik aşıldığında sorumlu kişiye uyarı gider.
08Çalışma modelleri
Bu hizmette çalışma modelleri
- 01
Proje bazlı
Sabit kapsam, sabit fiyat ve belirli teslim tarihi
Kapsamı belli, teslim tarihi olan işler için.
- Yazılı kapsam ve kabul ölçütleri
- Sabit fiyat ve belirli teslim tarihi
- Teslim ve kabul adımları sözleşmede
- 02
Bakım ve destek
Aylık sözleşmeli, SLA'lı bakım, destek ve geliştirme saati
Yayındaki bir sistemin sürekliliği için.
- Aylık sözleşme ve SLA
- İzleme, güncelleme ve hata düzeltme
- Aylık geliştirme saati
09Sık sorulan sorular
API yazılımı hakkında sık sorulan sorular
REST mi GraphQL mi seçmeliyiz?
Servisi dış iş ortakları kullanacaksa REST genellikle daha kolay benimsenir. Kendi web ve mobil arayüzleriniz çok sayıda farklı ekran için esnek sorgu istiyorsa GraphQL avantaj sağlar. İkisini birlikte kullanan yapılar da kurulabilir.
API yazılımı yaptırma fiyatları neye göre değişir?
Uç nokta ve kaynak sayısı, arka plandaki sistemlerin erişilebilirliği, yetki modelinin karmaşıklığı, webhook ve test ortamı ihtiyacı ile beklenen trafik hacmi belirleyicidir. Eski bir sistemin önüne servis koymak, sıfırdan veri modeli kurmaktan farklı bir iş yüküdür.
Elimizde yalnızca eski bir veritabanı var, üzerine API yazılabilir mi?
Evet. Veritabanını değiştirmeden önüne bir servis katmanı konabilir; böylece dış dünya tablolara değil, kontrollü uç noktalara erişir. Zamanla eski sistem değiştirilse bile servisin sözleşmesi aynı kaldığı için entegrasyonlar etkilenmez.
API yazılımı için firma seçerken nelere bakmalıyız?
Dokümantasyonun nasıl üretildiğini, sürüm değişikliklerinin nasıl yönetildiğini, yetki kontrolünün nasıl test edildiğini ve servisin yayından sonra kim tarafından izleneceğini sorun. Örnek bir uç nokta için hata yanıtının nasıl görüneceğini istemek de yaklaşım hakkında fikir verir.
İş ortaklarımız servisi kullanmaya nasıl başlar?
Her ortağa test ortamı için ayrı anahtar verilir, dokümantasyon ve örnek isteklerle denemelerini yaparlar. Test başarıyla tamamlandığında canlı ortam anahtarı tanımlanır ve kullanım panelden izlenir.
Yayındaki API'de değişiklik yapınca mevcut entegrasyonlar bozulur mu?
Geriye dönük uyumlu değişiklikler mevcut sürümde yapılır, uyumu bozan değişiklikler yeni sürüme gider. Eski sürüm, ortaklarınıza duyurulan bir geçiş dönemi boyunca çalışmaya devam eder.
10İlgili hizmetler