- Konu sahibi
- #1
API entegrasyonu, iki farklı yazılımın belirli kurallar üzerinden veri alışverişi yapmasını veya birbirinin işlevlerini kullanmasını sağlamaktır. Bir uygulama API üzerinden istek gönderir, diğer uygulama bu isteği işler ve genellikle JSON biçiminde bir yanıt döndürür. Böylece sistemleri doğrudan birbirinin veritabanına bağlamak yerine kontrollü bir iletişim katmanı kullanılır.
Örneğin bir e-ticaret uygulaması, kargo firmasının API’sine gönderi numarasını ileterek kargonun durumunu öğrenebilir. Kullanıcı sipariş sayfasını açtığında uygulamanız kargo API’sine istek gönderir, dönen durum bilgisini kendi arayüzünde gösterir. Bu işlemde e-ticaret uygulaması istemci, kargo sistemi ise API sağlayıcısıdır.
Bu bölüm, HTTP üzerinden istek ve yanıtla çalışan API entegrasyonunu örnekler. Diğer iletişim biçimlerinin ayrıntıları farklı olabilir. İstekte genellikle API adresi, HTTP yöntemi, başlıklar, kimlik doğrulama bilgisi, sorgu parametreleri veya veri gövdesi yer alır. Sunucu isteği değerlendirdikten sonra bir HTTP durum kodu ve varsa yanıt gövdesi döndürür.
Yaygın HTTP yöntemleri şunlardır:
Bir uygulamanın
Başarılı yanıt, oluşturulan kaydın kimliğini içerebilir. İstek kimlik doğrulaması olmadan gönderilirse 401, kullanıcının yetkisi yetersizse 403, gönderilen veri hatalıysa 400 dönebilir. Bu nedenle yalnızca yanıt gövdesini değil, HTTP durum kodunu da kontrol etmek gerekir.
API anahtarını HTML, mobil uygulama paketi veya herkese açık Git deposuna koymak en yaygın güvenlik hatalarındandır. Diğer önemli hatalar, yalnızca 200 yanıtını başarı kabul etmek, timeout tanımlamamak, API değişikliklerini takip etmemek ve üçüncü taraf servisin geçici olarak çalışmaması durumunda kullanıcıya boş ekran göstermektir. Entegrasyon kodu, sağlayıcıya tamamen bağımlı bırakılmak yerine kendi uygulamanızda doğrulama ve hata yönetimiyle çevrelenmelidir.
Hayır. GraphQL, SOAP veya gRPC gibi farklı API yaklaşımları kullanılabilir. Webhook ise bir olay bildirimi yöntemidir; bu sistemlerle birlikte çalışabilir. Seçim, sağlayıcının sunduğu arayüz ve uygulamanın veri ihtiyacına bağlıdır.
Sorgulama yaklaşımında uygulamanız veriyi almak için karşı sisteme istek gönderir. Webhook’ta ise olay gerçekleştiğinde karşı sistem sizin belirlediğiniz adrese otomatik bildirim gönderir. Sık aralıklarla sorgulama yerine olay odaklı bildirim gerektiğinde webhook daha uygun olabilir.
Örneğin bir e-ticaret uygulaması, kargo firmasının API’sine gönderi numarasını ileterek kargonun durumunu öğrenebilir. Kullanıcı sipariş sayfasını açtığında uygulamanız kargo API’sine istek gönderir, dönen durum bilgisini kendi arayüzünde gösterir. Bu işlemde e-ticaret uygulaması istemci, kargo sistemi ise API sağlayıcısıdır.
API entegrasyonu nasıl çalışır?
Bu bölüm, HTTP üzerinden istek ve yanıtla çalışan API entegrasyonunu örnekler. Diğer iletişim biçimlerinin ayrıntıları farklı olabilir. İstekte genellikle API adresi, HTTP yöntemi, başlıklar, kimlik doğrulama bilgisi, sorgu parametreleri veya veri gövdesi yer alır. Sunucu isteği değerlendirdikten sonra bir HTTP durum kodu ve varsa yanıt gövdesi döndürür.
Yaygın HTTP yöntemleri şunlardır:
- GET: Veri okumak için kullanılır.
- POST: Yeni veri oluşturmak veya bir işlem başlatmak için kullanılır.
- PUT: Hedef kaynağın temsilini bütünüyle oluşturma veya değiştirme isteğidir.
- PATCH: Bir kaynağa kısmi değişiklik uygular.
- DELETE: Veri silmek için kullanılır.
Somut entegrasyon örneği
Bir uygulamanın
example.com üzerindeki test servisine kullanıcı bilgisi göndermesi gerektiğini varsayalım. Sunucu tarafında yapılabilecek basit bir istek mantığı şöyledir:
HTTP:
POST https://example.com/api/users
Content-Type: application/json
Authorization: Bearer TEST_TOKEN
{
"name": "Ayşe",
"email": "[email protected]"
}Başarılı yanıt, oluşturulan kaydın kimliğini içerebilir. İstek kimlik doğrulaması olmadan gönderilirse 401, kullanıcının yetkisi yetersizse 403, gönderilen veri hatalıysa 400 dönebilir. Bu nedenle yalnızca yanıt gövdesini değil, HTTP durum kodunu da kontrol etmek gerekir.
API entegrasyonu yaparken izlenecek adımlar
- Entegrasyon amacını netleştirin. Hangi verinin okunacağını, yazılacağını veya hangi işlemin başlatılacağını belirleyin.
- API dokümantasyonundan uç nokta adreslerini, HTTP yöntemlerini, zorunlu alanları, kimlik doğrulama biçimini ve hata yanıtlarını inceleyin.
- Önce test ortamında veya sınırlı yetkili bir hesapla bağlantıyı deneyin. Gerçek kullanıcı verilerini ilk testte kullanmayın.
- Gizli yetki gerektiren isteği sunucu tarafında oluşturun ve sırları istemciye göndermeyin. Herkese açık istemci isteğinde sağlayıcının CORS ve erişim kurallarını kontrol edin.
- Yanıt durum kodunu, veri biçimini ve beklenmeyen alanları kontrol edin. Hataları kullanıcıya teknik token veya gizli bilgi göstermeden açıklayın.
- Zaman aşımı, geçici ağ hatası ve hız sınırı gibi durumlar için kontrollü tekrar mekanizması ekleyin. Aynı POST isteğini koşulsuz tekrarlamanın mükerrer kayıt oluşturabileceğini unutmayın.
- Başarılı ve hatalı istekleri hassas verileri loglamadan kaydedin; ardından test, izleme ve bakım sürecini planlayın.
| İhtiyaç | Uygun yaklaşım | Dikkat edilecek nokta |
|---|---|---|
| Tarayıcıdan herkese açık veri okumak | İstemci tarafı istek | CORS ve görünür API anahtarı riski |
| Gizli anahtarla işlem yapmak | Sunucu tarafı istek | Anahtarı kullanıcıya göndermemek |
| Uzun süren işlemi takip etmek | Asenkron görev veya webhook | Tekrar ve durum takibi |
| Birden fazla servisi birleştirmek | Ara katman veya servis katmanı | Hata yönetimi ve veri eşleme |
Sık yapılan hatalar
API anahtarını HTML, mobil uygulama paketi veya herkese açık Git deposuna koymak en yaygın güvenlik hatalarındandır. Diğer önemli hatalar, yalnızca 200 yanıtını başarı kabul etmek, timeout tanımlamamak, API değişikliklerini takip etmemek ve üçüncü taraf servisin geçici olarak çalışmaması durumunda kullanıcıya boş ekran göstermektir. Entegrasyon kodu, sağlayıcıya tamamen bağımlı bırakılmak yerine kendi uygulamanızda doğrulama ve hata yönetimiyle çevrelenmelidir.
Sık sorulan sorular
API entegrasyonu için mutlaka REST kullanmak gerekir mi?
Hayır. GraphQL, SOAP veya gRPC gibi farklı API yaklaşımları kullanılabilir. Webhook ise bir olay bildirimi yöntemidir; bu sistemlerle birlikte çalışabilir. Seçim, sağlayıcının sunduğu arayüz ve uygulamanın veri ihtiyacına bağlıdır.
API ile webhook arasındaki temel fark nedir?
Sorgulama yaklaşımında uygulamanız veriyi almak için karşı sisteme istek gönderir. Webhook’ta ise olay gerçekleştiğinde karşı sistem sizin belirlediğiniz adrese otomatik bildirim gönderir. Sık aralıklarla sorgulama yerine olay odaklı bildirim gerektiğinde webhook daha uygun olabilir.
