Günümüzde E-ticaretin gelişmesiyle API’lerin kullanımı ciddi anlamda artmıştır. Bununla birlikte servis bazlı ve çözüm odaklı bir çok üründe müşterilerine API’ler ile hizmet sağlamaktadır.
Bu API’ler ile iş modellerimiz geliştiği kadar, mimarisi ile bizi sıkıntıya düşerecek API’lerde türemektedir.
İyi tasarlanmış bir API hem geliştiricisine, hemde istemcisine hizmet edecektir. Bunun için standartlarına uymamız gerekmektedir.
Geçmişten Günümüze API Türleri
Eski sistemler SOAP kullanmaktadır. Zamanında revaçta olan Microsoft sunduğu güzel teknolojiydi. Her teknoloji gibi doğdu, gelişti ve emekliye ayrılıyor. Eski sistemlerde hala karşılaşanınız oluyordur. Bu makaleyi yazdığım günlerde üzerinde çalıştığım E-Ticaret sistemine Yurtiçi Kargo’nun SOAP servislerini entegre ediyordum. PHP ile SOAP kullanmak .NET teknolojileri kadar keyifli olmasa da, güzel insanların hazırlamış olduğu PHP kütüphaneleri işlerimizi kolaylaştırmaktadır.
SOAP ile RESTful Arasındaki Farklar
Bu iki teknolojiyi karşılaştırmak için bir kriteri ele alırsak, bugünün standartları ve uzun ömürlülüğü düşünüyorsak kesinlikle RESTful açık ara kazanan olacaktır.
Neden SOAP Yerine RESTful?
- HTTP üzerinden çalıştığı için, SOAP gibi istemcide kütüphanesine ihtiyaç duymaz
- İstediğiniz dilde geliştirebilirsiniz
- JSON ve XML destekler
- Metod adlarınızı göstermeden geri döndürebilirsiniz
- CRUD işlemlerini destekler
RESTful Servislerimizi Nasıl Tasarlamalıyız?
API servislerimizi tasarlarken olabildiğince sade, anlamlı ve sürdürülebilir olması gereklidir. Kötü bir API tasarımı hem developer, hemde istemci tarafında çok maliyetli olmaktadır.
URL’leriniz Anlamlı Olmalıdır
API servisleriniz istemcilerinize bir çok veri sağlayacak şekilde oluşturacaksınız. Bu bağlantılarında bir standartı olmalıdır.
En önemliside API versiyonlamasını yapmanız çok önemlidir. Uygulamanız ile beraber API’lerinizde gelişecektir. API’lerinizi kullanan istemcilerde bu değişiklikleri her zaman uygulamayabilir ve aranızda bağlantı kopukluklarına sebep olabilir. Özellikle major düzenlemeler yapıyorsanız, versiyonlamanın önemi çok büyüktür. Örnek bağlantı isimlendirmesi;
/v1/users Bağlantı noktalarınız çoğul isimlendirme olmalıdır
/v1/users/1 Bir kullanıcıyı çağıracaksanız
/v1/users/1/posts Kullanıcının yazılarını çağıracaksanız
Filtreleme, sayfalama, sıralama için aşağıdaki gibi bağlantılar oluşturabilirsiniz. Sıralama işlemlerinde querystringinizdeki – (tire) DESC, + veya herhangi bir sembol kullanmamak ASC sıralamayı temsil etmektedir.
/v1/users?name=Hüseyin
/v1/users?page=1&per_page=10
/v1/users?sort=-surname
CRUD İşlemleri
CRUD, dört temel veritabanı işlemi olan oluşturma, okuma, güncelleştirme ve silme işlemlerini temsil eder. Create, Read, Update ve Delete kelimelerinin baş harflerinden oluşur. HTTP hizmeti RESTful API’ler ile CRUD işlemlerini modelleyebilir.
| Eylem | HTTP Yöntemi | Örnek URL |
| Tüm ürünlerin listesini alma | GET | /v1/products |
| ID’ye göre ürün çağırma | GET | /v1/products/123 |
| Kategoriye göre ürün çağırma | GET | /v1/products?kategori=elektronik |
| Yeni ürün oluşturma | POST | /v1/products |
| Ürün güncelleştirme | PUT | /v1/products/123 |
| Ürün silme | DELETE | /v1/products/123 |
HTTP Durum Kodları
Şimdiye kadar bir çok API entegrasyonu ile deneyim kazanmış biri olarak şunu söylemem gerekiyor ki, önemli ama hiç dikkat edilmeyen konulardan biridir.
Tarayıcımız bu durum kodlarını HTTP Header ile almaktadır. Bu bize yapılan istekler hakkında bilgi vermektedir.
Durum kodları beş kategoride toplanmıştır.
- 100 seviyesi durum kodları sunucu istekleri konusunda bilgilendirme verir
- 200 seviyesi durum kodları başarılı sunucu isteklerini bildirir
- 300 seviye durum kodları yönlendirmeler hakkında bilgi verir
- 400 seviye durum kodları istemci hataları hakkında bilgi verir
- 500 seviye durum kodları sunucu iç hataları hakkında bilgi verir
| Durum Kodu | Açıklama |
| 200 | İstek işlemi başarılı |
| 201 | Kayıt ekleme işlemi başarılı |
| 204 | Güncelleme ve silme başarılı |
| 304 | Herhangi bir değişiklik olmadığında |
| 400 | Yapılan istek hatalı veya veri doğrulanmıyorsa |
| 401 | Kimlik doğrulama hatası |
| 403 | Yetki olmayan adrese erişim |
| 404 | Veri bulunmuyorsa, hiç yoksa |
| 500 | Sunucu iç hatası |
Tüm listeye ulaşmak için daha önceden yayınladığımız HTTP Sunucu Durum Kodları (HTTP Status Codes) yazımızı inceleyebilirsiniz.
HTTP Header, CORS ve Güvenlik
Headerlar bir HTTP istek veya cevabının başında bulunan veridir. Header paketi Http Header, body ve trailer alanlarından oluşur. Body terimi sizi HTML’ye götürmesin 🙂
Header beraberinde bize bir çok bilgi getirir. Yaptığımız istek ve aldığımız cevapları içinde header bulunmaktadır. Makaleyi uzatmamak için bunları açıklamaya girmeyeceğim. Özetle güvenlik, içerik tipleri (Content-Type), dil, istek tipleri (GET, POST) hakkında tarafımıza bilgi verir.
CORS güvenlik API güvenliğimiz için çok önemlidir. Gelen istekleri URL, Header veya HTTP metodları (GET, POST) bazında sınırlandırmalar sunar.
API’ler beraberinde bir çok güvenlik zaafiyeti getirir. Bunların çoğundan kurtulmak için mutlaka HTTPS üzerinden yayın yapın!
API’nizden Dönen Cevapların Standartları Olsun (Response Handling)
Bu konuda çok açık konuşacağım. API’lerinizi kullanan yazılımcı arkadaşınızın size sövmesini istemiyorsanız, dönen cevapların bir standartı olsun. 🙂
Çünkü yazılımlarımızı geliştirirken API servislerini kullanmak için fonksiyonlar oluştururuz. Bunlar biribirinden farklı olursa, hazırladığımız fonksiyonlar pek işe yaramıyor. Söve söve düzenlemeler yapmak zorunda kalıyoruz 🙂
Benim kullandığım örnek bir response;
[
"status" => "success/failure",
"statusCode" => 200,
"locale" => "tr",
"systemTime" => 1591705159,
"data" => [],
"error" => [
"message" => "Kullanıcı adı geçersizdir",
"internalMessage" => "Kullanıcı adında geçersiz karakterler bulunmaktadır",
"help" => "http://www.huseyinyildirim.com/destek/"
]
];API Dökümantasyonu
API’lerinizi kullanacaklar için servislerinizin nasıl çalıştığını anlatmak, ne gönderip ne alacaklarını belirtmek gereklidir. Malum her yiğidin yoğurt yemesi farklı oluyor. PHP veya .NET teknolojilerinden hangisi kullanıyorsanız dökümantasyon işlemlerinizi sağlayacak araçlar bulunmaktadır. En sık kullanılanlar