RESTful API Uygulamaları Nasıl Tasarlamalıyız

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?

  1. HTTP üzerinden çalıştığı için, SOAP gibi istemcide kütüphanesine ihtiyaç duymaz
  2. İstediğiniz dilde geliştirebilirsiniz
  3. JSON ve XML destekler
  4. Metod adlarınızı göstermeden geri döndürebilirsiniz
  5. 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.

EylemHTTP YöntemiÖrnek URL
Tüm ürünlerin listesini almaGET/v1/products
ID’ye göre ürün çağırmaGET/v1/products/123
Kategoriye göre ürün çağırmaGET/v1/products?kategori=elektronik
Yeni ürün oluşturmaPOST/v1/products
Ürün güncelleştirmePUT/v1/products/123
Ürün silmeDELETE/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 KoduAçıklama
200İstek işlemi başarılı
201Kayıt ekleme işlemi başarılı
204Güncelleme ve silme başarılı
304Herhangi bir değişiklik olmadığında
400 Yapılan istek hatalı veya veri doğrulanmıyorsa
401Kimlik doğrulama hatası
403Yetki olmayan adrese erişim
404Veri bulunmuyorsa, hiç yoksa
500Sunucu iç hatası
En sık kullanılan durum kodları

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

  1. Swagger
  2. Doxygen
  3. ReDoc
  4. RAML
  5. Docusaurus

Bir Cevap Yazın