Günümüzün yazılım dünyasında, uygulamaların ve hizmetlerin birbiriyle iletişim kurması büyük bir önem taşımaktadır. Bu iletişimin temel yapı taşlarından biri de API(Uygulama Programlama Arayüzü – Application Programming Interface )’lerdir.
Bu yazıda, API nedir sorusundan başlayarak, farklı API tiplerini, temel tasarım prensiplerini ve pratiklerini ele alacağız.
API Nedir?
Application Programming Interface — Uygulama Programlama Arayüzü
Farklı yazılım uygulamalarının birbirleriyle iletişim kurmasını ve veri alışverişi yapmasını sağlayan bir arayüzdür.
Uygulamalar arasındaki iletişim ve veri alışverişi, birden fazla hizmetin işlevselliğini kendi hizmetlerimize entegre etme olanağı sunar. Bu sayede, yeniden kullanılabilirlik artar, pratik bir şekilde yeni özellikleri hizmetimize ekleme olanağı sağlanır ve geliştirme süreçleri hızlanır.
API Tipleri Nelerdir?
API’ler, farklı ihtiyaçlara ve kullanım senaryolarına göre çeşitlilik gösterir.
REST
Representational State Transfer
Web servisleri için en popüler mimarilerden biridir. HTTP protokolü üzerinde çalışır ve genellikle JSON veya XMLformatında veri alışverişi yapar.
RESTful API’ler, kaynaklara erişmek için standart HTTP yöntemlerini (GET, POST, PUT, DELETE) kullanır.
SOAP
Simple Object Access Protocol
XML tabanlı bir mesajlaşma protokolüdür. Daha karmaşık ve katı bir yapıya sahiptir. Güvenlik ve işlem yönetimi gibi özellikleri nedeniyle özellikle finans ve telekomünikasyon sektörlerinde daha fazla tercih edilir.
GraphQL
GraphQL, 2012’de Facebook tarafından dahili olarak geliştirilen ve 2015’te herkese açık olarak yayınlan bir sorgu dili, mimari stil ve API’leri oluşturup işlemeye yönelik araçlar kümesidir.
Geleneksel REST API’lerinin aksine, GraphQL ile istemciler gereksiz veri taşımadan sadece istedikleri alanları çekebilir, böylece ağ trafiğini ve veri işlemeyi optimize eder. Bu esneklik, daha verimli ve ölçeklenebilir uygulamaların geliştirilmesine yardımcı olur ve geliştiricilere API’lerle etkileşimde daha fazla kontrol sağlar.
gRPC
gRPC, Google tarafından geliştirilmiş açık kaynaklı bir uzaktan prosedür çağrısı (RPC) “framework”üdür. Mikroservisler arasında yüksek performanslı, düşük gecikmeli ve platformlar arası iletişimi kolaylaştırmak için tasarlanmıştır. gRPC, veri serileştirme için Protocol Buffers’ı kullanır. Çift yönlü akış ve verimli bant genişliği kullanımı sağlar.
Temel Prensipler
API tasarımı, sadece teknik bir süreç olmanın ötesinde, kullanıcı deneyimini ve iş süreçlerini doğrudan etkileyen kritik bir unsurdur. Geliştiricilerin ihtiyaçlarını karşılamanın yanı sıra son kullanıcıların beklentilerini de karşılamak API’nizi etkili kılacaktır.
Tutarlılık
API’yi öğrenme ve kullanma kolaylığı sağlamak için her şeyi aynı mantık ve kurallarla yapmak gerekmektedir. Geliştiricilerin takip ettiği standartlar, tutarlılığı arttırarak API’yi öngörülebilir, hızlı anlaşılabilir ve mantıklı bir noktada konumlandıracaktır.
Eğer yeni bir kullanıcı eklemek için “POST /users” adresini kullanıyorsanız, yeni bir ürün eklemek için de “POST /products” adresini kullanmalısınız. “POST” metodu her zaman yeni bir şey eklemek için kullanılır ve adres eklemek istediğiniz şeyin adı ile sonlanır. Aynı işlem için farklı metod ve adres yapısı kullanmak, API’yi kullanan kişiler için zorlayıcı durumları ortaya çıkaracaktır.
Ayrıca, hata mesajları ve durum kodları gibi diğer başlıklar için de tutarlılık önem arz etmektedir. Eğer API bir bilgiyi bulamadığında “404 Not Found” hatası veriyorsa, bu tüm kaynaklar için geçerli olmalıdır.
“GET /users/123” isteği karşılık bulamadığında “404” durum kodu ile cevap veriyorsa, “GET /products/456” isteği de ürün yoksa aynı kodu kullanmalıdır.
Anlaşılabilirlik
API’yi kullanan geliştiriciler, ne yapması gerektiğini ve nasıl kullanacağını hızlı bir şekilde kavrayabilmesi için fonksiyonlar, metodlar ve endpoint’ler açık ve net bir şekilde isimlendirilmeli, tutarlılık prensibi ile birlikte, karmaşık kullanımlardan kaçınılmalıdır.
Kullanıcı silme işlemi için “DELETE user/{userId}” isteği kullanıldığında; adres, http yöntemi ve yaptığı iş birbirini destekleyecek şekilde açıklayıcıdır. Bu işlem için “DELETE delete/{id}” gibi bir adres kullansaydık ek açıklamalar yapmak zorunda kalarak anlaşılabilirlik seviyesini düşürmüş olurduk.
Versiyonlama
API’ler zaman içinde evrilir ve değişir. Versiyonlama, bir API’nin zaman içindeki bu dönüşümüyle ortaya çıkan farklı sürümlerinin uyumlu kullanımını sağlayan bir yöntemdir. API gelişip değişirken, eski sürümü kullanan uygulamalar çalışmaya devam edebilir. Geliştiricilere API’nin hangi sürümünü kullandıklarını net bir şekilde belirtme imkanı sunar, böylece beklenmedik hataların önüne geçilir.
https://api.ornek.com/v1/users
https://api.ornek.com/v2/usersVersiyonlama yöntemi olarak; URL’de ilgili versiyonun belirtilmesi kullanılabilir. “https://api.ornek.com/v1/users” adresinde “v1” ilgili API’nin 1. versiyonunun kullanıldığını anlatmaktadır. Eğer API’nin yeni bir sürümü yayınlanırsa ve bazı değişiklikler yapılırsa, bu yeni sürüm “v2” olarak sunulur ve “https://api.ornek.com/v2/users” adresi ile yeni özellikler kullanılabilir. Bu sayede eski versiyonların ne kadar hayatına devam edeceğini, ne zaman bu özelliklerin kullanımdan kaldırılacağı gibi detaylar da verimli yönetilebilir.
Stateless Tasarım
API’nin her isteği bağımsız olarak işlemesi ve sonuçlandırması gerekir. Sunucu tarafında herhangi bir oturum veya durum bilgisi tutmamalı. Bu yaklaşımda, her istek gerekli olan bilgilerin tamamını içerir ve API önceki istekleri bilmek zorunda kalmadan mevcut parametleri ile sürecini yürütebilir. Bu şekilde, API’nin ölçeklenebilirliği artar ve isteklerin daha basit hale gelmesi sağlanır.
“GET /profile” isteği ile birlikte “Authorization” başlığında token bilgisi bulunur. API bu token bilgisini doğrular ve size kullanıcı verilerini verebilir. Sizin daha önce oturum açıp açmadığınızı veya hangi adımlardan geçtiğinizi bilmek zorunda değildir. Böylece her istek kendi içinde tam ve bağımsızdır.
Hata Yönetimi
Kullanıcılara anlamlı ve tutarlı hata mesajları iletmek, beklenen durumların karşılanmadığı senaryolarda, kullanıcı ve geliştiricilerin doğru bir şekilde yönlendirilmesini sağlar. Ayrıca geliştiricilerin karşılaştıkları sorunları hızlıca tespit etmelerine ve çözmelerine yardımcı olur. Bunlarla birlikte API’nin nasıl kullanılacağı konusunda netlik sağlanır ve kullanıcı deneyimini iyileştirir.
Geçersiz bir istek yapıldığında, API “400 Bad Request” hata kodu ve açıklayıcı bir mesaj ile cevabı oluşturmalıdır. Eğer istenen kaynak bulunamazsa, “404 Not Found” hata kodu ile “Kullanıcı bulunamadı” gibi bir mesaj verilmelidir. Böylece, HTTP metodları ve açıklamaları doğru şekilde kullanılmış olur, geliştiriciler hatanın ne olduğunu anlayarak gerekli aksiyonları gerçekleştirebilir.
Güvenlik
Yetkisiz erişimlere ve olası saldırılara karşı korunma sağlayan kritik bir tasarım prensibidir. Sağlıklı hizmet vermek ve güvenilir bir kaynak olmak için, kullanıcı verilerinin ve sistem kaynaklarının güvende tutulması önem arz etmektedir.
API’ye erişim sağlamak için yapılan her istekte bir kimlik doğrulama token’ı veya API anahtarı kullanmak, verilerin iletimi sırasında şifreleme kullanmak başlıca önlemler arasındadır.
Ek olarak, istek sayısını sınırlama (rate limiting) ve güvenlik duvarları gibi önlemlerle API’nin kötü niyetli kullanımlara karşı korunması sağlanabilir.
Pratikler
API tasarımı, sadece temel prensiplerle sınırlı olmayan, aynı zamanda daha farklı pratiklerin de dikkate alınmasını gerektiren bir süreçtir. Bu ileri düzey uygulamalar, API’nizin performansını, güvenliğini ve kullanılabilirliğini artırarak hem geliştiricilere hem de son kullanıcılara daha kaliteli bir hizmet sunmanızı sağlar.
Kimlik Doğrulama
Authentication
API’ye erişim sağlamak isteyen kullanıcıların veya uygulamaların gerçekten kim olduklarını doğrulamak için kullanılan bir güvenlik yöntemidir. Bu sayede, API’nin sadece yetkili ve tanınmış istemcilere hizmet vermesi sağlanır, yetkisiz erişimler engellenir.
API’yi kullanmak isteyen bir uygulama, her istekte bir API anahtarı veya token gönderebilir. Bu token, oturum açma işlemi sırasında veya önceden verilen bir kimlik bilgisi olabilir. API sunucusu, gelen istekteki token’ı kontrol eder ve geçerli ise isteği işler. Eğer token geçersiz veya eksikse, API sunucusu isteği reddeder ve uygun bir hata mesajı döndürür. Bu şekilde, sadece doğru kimlik bilgilerine sahip olanların API’yi kullanmasına izin verilmiş olur.
- API Anahtarları (API Keys): Her istemciye özel bir anahtar verilir ve bu anahtar API‘ye yapılan her istek ile gönderilir.
- Temel Kimlik Doğrulama (Basic Authentication): Kullanıcı adı ve şifre, istek başlığında Base64 kodlamasıyla gönderilir.
- Open Authorization (OAuth): Yetkilendirme sunucusu üzerinden erişim token’ları kullanılarak kimlik doğrulama yapılır.
- JSON Web Token (JWT): İmzalanmış JSON nesneleri kullanılarak kullanıcı bilgileri güvenli bir şekilde taşınır.
Yetkilendirme
Authorization
API’ye erişen kullanıcının veya uygulamanın hangi kaynaklara erişebileceğini ve hangi işlemleri yapabileceğini belirleyen bir güvenlik sürecidir.
Kimlik doğrulama (Authentication) kullanıcının kim olduğunu doğrularken, yetkilendirme bu kullanıcının ne yapmaya yetkili olduğunu belirler. Bu süreç ile birlikte hassas verilere ve işlemlere sadece izin verilen kullanıcılar erişebilir.
E-ticaret platformunda müşteri hizmetleri temsilcisi, müşterilerin siparişlerini görüntüleyebilir ve güncelleyebilir, ancak ödeme sistemine veya yönetici ayarlarına erişemez. Bu gibi özelleştirme yönetim ve kontrolleri, API’nin yetkilendirme mekanizmaları ile yönetilir. Benzer şekilde, bir öğrenci bilgi sisteminde öğrenciler kendi notlarını ve ders programlarını görebilir fakat öğretmenler tüm öğrencilerin notlarını güncelleyebilir.
Sayfalandırma
Pagination
API’den büyük veri kümeleri çekerken verilerin parçalara bölünerek sunulmasını sağlayan bir yöntemdir. Hem sunucu hem de istemci tarafında performansı artırır ve kaynak kullanımını optimize eder.
Örneğin, bir e-ticaret sitesinde binlerce ürün olduğunu düşünelim. Tüm ürünleri tek bir API çağrısıyla almak hem yavaş olacaktır hem de gereksiz veri transferine neden olacaktır. Sayfalandırma sayesinde, istemci her seferinde belirli bir sayıda ürünü (örneğin, 20 ürün) alabilir ve kullanıcı arayüzünde bu verileri sayfa sayfa gösterebilir.
Sayfalandırma genellikle URL parametreleri kullanılarak gerçekleştirilir.
GET /products?page=2&limit=20 # -> İkinci sayfadaki 20 ürünü getirirBurada page parametresi hangi sayfanın istendiğini, limit parametresi ise her sayfada kaç öğe olacağını belirler. Büyük veri setlerinin yönetimini kolaylaştırır, daha hızlı yüklenen ve daha kolay gezilebilen sayfalarda, kullanıcı deneyimini iyileştirir.
Offset Tabanlı Sayfalandırma
Offset-Based Pagination
GET /items?offset=20&limit=10 # -> 21. öğeden başlayarak 10 öğeyi getirir.Sayfa Numarası ile Sayfalandırma
Page Number Pagination
GET /items?page=3&limit=15 # -> 3. sayfadaki 15 öğeyi getirir.Anahtar Tabanlı Sayfalandırma
Keyset Pagination
GET /items?lastId=50&limit=10 # -> id değeri 50’den büyük olan sonraki 10 öğeyi getirir.Filtreleme
Filtering
API’den çekilen verilerin belirli kriterlere göre kısıtlanmasını sağlayan yöntemdir. İstemci sadece ihtiyaç duyduğu verileri alır ve gereksiz veri transferi önlenir. Hem ağ trafiğini azaltır hem de uygulamanın performansını artırır.
GET /products?category=electronicsE-ticaret API’sinde belirli bir kategorideki ürünleri listelemek için yukarıdaki istek yapılabilir. Eğer sadece stokta olan ürünleri görmek istiyorsanız, aşağıdaki gibi bir filtre uygulayabilirsiniz.
GET /products?inStock=trueBu şekilde, istemci sadece gerekli verileri çeker ve kullanıcıya daha hızlı ve verimli bir deneyim sunar.
Başlıca filtreleme yöntemleri:
Basit Parametre Filtreleme
GET /products?category=electronics # -> Kategori değeri “electronics” olan ürünleri getirir.Çoklu Parametre Filtreleme
GET /products?category=electronics&brand=apple&inStock=true # -> Bu istek, “electronics” kategorisinde, markası “apple” olan ve stokta bulunan ürünleri getirir.Karşılaştırma Operatörleri ile Filtreleme
GET /products?price_gt=100&price_lt=500 # -> Fiyatı 100’den büyük ve 500’den küçük olan ürünleri getirir.Mantıksal Operatörler ile Filtreleme
GET /products?filter=(category:electronics OR category:appliances)&inStock=true # -> Kategori değeri “electronics” veya “appliances” olan ve stokta bulunan ürünleri getirir.Dokümantasyon
Documentation
İhtiyaç duyulan bilgilere hızlıca ulaşmak ve entegrasyon sürecini kolaylaştırmak için API’nin nasıl kullanılacağını açıklayan ve geliştiricilere rehberlik eden yazılı materyaller gerekir. İyi bir dokümantasyon, API’nın fonksiyonlarını, metodlarını, parametrelerini, yanıt formatlarını ve olası hata durumlarını açık ve anlaşılır bir şekilde belirtir.
API Referans Dokümantasyonu: Bir web sitesi veya portal üzerinden erişilebilen Markdown veya HTML formatındaki dokümanlar ile tüm API endpoint’leri, parametreleri, yanıt formatları ve hata kodları detaylı bir şekilde listelenir.
Otomatik / Interaktif Dokümantasyon: Kod yorumlarından veya API tanım dosyalarından otomatik olarak oluşturulur ve sürekli güncellenir. Swagger (OpenAPI), RAML veya API Blueprint kullanılarak API’nin tanımı yapılır ve bu tanıma dayalı interaktif dokümantasyon oluşturulur. Geliştiriciler, Swagger UI gibi araçlar sayesinde dokümantasyon üzerinden API’yi doğrudan deneyebilirler; parametreleri girip gerçek zamanlı olarak istek gönderebilir ve yanıtları görebilirler.
Kod Örnekleri ve SDK’lar: Python, JavaScript veya Java gibi farklı programlama dillerinde kullanılabilecek hazır kod örnekleri ve açık kaynaklı SDK’lar sunarak geliştiricilerin API’yi kolayca entegre etmelerini sağlar.
Test
API’nin beklenen şekilde çalıştığını ve olası hatalardan arındırıldığını doğrulamak için yapılan işlemlerdir. Geliştiricilerin ve kullanıcıların güvenli ve sorunsuz bir deneyim yaşaması için önem arz etmektedir. Ayrıca iyi bir test süreci sayesinde, API’nin fonksiyonları, performansı ve güvenliği hakkında tespitler yapılabilir ve gerektiğinde iyileştirmeler yapılır.
- Birim Testleri: En küçük birimlerin (fonksiyonlar veya metodlar) bağımsız olarak test etmesi sürecidir.
- Entegrasyon Testleri: Birden fazla bileşenin veya servislerin, birlikte doğru çalışıp çalışmadığı kontrol edilir.
- Fonksiyonel Testler: API’nin işlevsel gereksinimleri karşıladığını doğrular. Bu tip testler içerisinde gerçek kullanıcı senaryolarına odaklanılır.
- Performans Testleri: API’nin belirli koşullar altında performansını ölçererek, yanıt sürelerini, işlem hızını ve kaynak kullanımını değerlendirir.
- Güvenlik Testi: API’nin güvenlik açıklarını ve zafiyetlerini belirlemek üzere gerçekleştirilen test sürecidir. Nihai olarak yetkisiz erişimler ve saldırılar simüle edilmeye çalışılır.
İzleme
Monitoring
API’nin performansını, kullanılabilirliğini ve güvenliğini gerçek zamanlı olarak izlemeyi sağlayan önemli bir tasarım prensibidir.
Performans iyileştirilmesi, sorunların hızlı tespit edilebilmesi ve kullanıcı deneyiminin geliştirebilmesi için API’nin ne kadar verimli çalıştığını, hangi isteklerin yapıldığını, yanıt sürelerini ve olası hata durumlarını sürekli olarak takip edebilirsiniz.
Bir e-ticaret API’sinde, aniden artan hata oranlarını monitoring araçlarıyla fark edebilirsiniz. Eğer “GET /products” isteği normalde 200 ms’de yanıt verirken bir anda 2 saniyeye çıkarsa, bu durum sunucuda bir performans sorunu olduğunu gösterir. İzleme sayesinde bu tür anomalileri hemen tespit edip müdahale edebilirsiniz. Ayrıca, hangi endpoint’lerin en çok kullanıldığını ve hangi saatlerde trafik yoğunluğunun arttığını gözlemleyerek, sunucu kaynaklarını buna göre optimize edebilirsiniz.
Esneklik ve Genişletilebilirlik
API, gelecekteki ihtiyaçlara cevap verebilecek şekilde esnek ve genişletilebilir olmalıdır. Modüler bir yapı benimseyerek yeni özelliklerin eklenmesi veya mevcut işlevselliğin değiştirilmesi sırasında minimum etki ile güncellemeler yapılabilir. Bu, API’nin uzun vadeli başarısı için kritiktir.
• Modülerlik: API’yi küçük, bağımsız ve yeniden kullanılabilir bileşenlere ayırmak, bakım ve genişletmeyi kolaylaştırır.
• Sürüm Kontrolü: Değişikliklerin ve yeni özelliklerin etkili bir şekilde yönetilmesi için sürüm kontrolü ve versiyonlama stratejileri uygulanmalıdır.
• Genişletilebilirlik Desenleri: Event-driven mimari veya plugin sistemleri gibi desenler kullanarak API’nin yetenekleri artırılabilir.
Bu yazıda, API tasarımının temel prensiplerini ve ileri düzey en iyi pratiklerini ele aldık. Bu prensipler ile yola çıkarak İyi tasarlanmış bir API, sadece işlevsellik sunmakla kalmaz, aynı zamanda geliştiricilerin ve kullanıcıların ihtiyaçlarını etkin bir şekilde karşılar.
API’nin başarısı, tasarımı ve geliştiricilerin onu ne kadar kolay kullanabildiği ile doğrudan ilişkilidir.
