Programlanabilir Web’e Giriş 101

Bu yazıda API (Application Programming Interface), yani Uygulama Programlama Arabirimi geliştirme hakkında gerek yaptığım araştırmalar, gerekse de incelediğim API servislerinden edindiğim tecrübeler doğrultusunda, API geliştirmek için dikkat edilmesi gereken noktalar ve inceliklerden bahsedeceğim.

API : 101

Öncelikle, API geliştirmeyi düşünüyorsanız, bir web servisi kurmaya ihtiyacınız var demektir. Bu da yazılım geliştirenlere hizmet sağlayacaksınız demek oluyor. Yani cicili bicili arayüzleri unutun. Salt (Raw) verinin dünyasına hoşgeldiniz.

Bir API servisi, son kullanıcıya hitap etmez. Yazılımcıdan yazılımcıya hitap eden (hatta buna D2D denmeli -developer 2 developer-) böyle bir servisi kurmak için, bir programcıdan fazlası olmanız gerekiyor. Lütfen beni yanlış anlamayın, fakat bir Yazılım Geliştiricisi ile bir Bilgisayar Programcısı arasında bariz farklar vardır. Ve bizim alanımız, Yazılım Geliştirme. Bu demektir ki kurduğunuz sistem, geliştirilebilir olmalı. Çünkü kullanıcılarınız, sizin servisiniz üzerinden, uygulamanızı programlayacaklar. Aynı zamanda öncesi ve sonrası hesaba katılmalı, yani sürekliliği olan bir sistem olmalı, ileride siz de servisinizi geliştireceksiniz, fakat sizin servisinizi geliştirmenize eş güdümlü olarak, kullanıcılarınız da kendi uygulamalarını güncelleyemeyebilirler, bu yüzden servisiniz versiyon değişiminde, kullanıcılarınızı etkilemeyecek şekilde tasarlanmalı.

Hiç bir developer angarya iş sevmez. Yani tekrarlanan işleri pek sevmeyiz. Aslında developer olmamızın sebeplerinden biri de budur, ki şuan bu konuya girmeyeceğim. Bu yüzden servisinizin “endpointleri” yani servis sunduğunuz uç noktalar, mantıksal bir yapı barındırmalı. Kullanıcı developer bu mantık yapısını algılayıp, gerekirse servisleri kendisi response kodlarla beraber keşfedebilmeli.

Heryerde olduğu gibi burda da güvenlik esas. Özellikle API dünyası güvenlik çıtasını üst noktalara çekmiştir (bknz; OAuth2, API Key) ..vs. Servisiniz çok güvenli olmalı. Çünkü kullanıcılara veri sisteminiz üzerinde okuma/yazma/güncelleme/silme gibi yetkiler vereceksiniz(elbette servisinizi sadece okuma olarak da tutabilirsiniz, bu servis türünüze bağlı tamamen)

Bu kadar ön bilgiden sonra örneklerle konuyu açıklamaya başlayalım.

1. URL adreslerinizi temiz ve basit tutun

API üzerinde kullanacağınız her kaynak için iki URL adres yapısı kullanın. Bu adresler üzerinde webde kullanılan fiilleri seçmeyin (get/post/put/delete..vs gibi). Örneğin Kitaplar koleksiyonu için bir api servisi oluşturduğumuzu varsayalım.

/kitaplar                 /kitaplar/1234

Kitaplar kaynağımız için iki kaynağımızı oluşturduk, iki kaynağımızı ve yönetmek için dört HTTP methodunu(POST, PUT, GET, DELETE) kullanırsak, gayet zengin bir işlem hacmine sahip olacağız.

/kitaplar => POST => Yeni kitap oluştur

/kitaplar => GET => Kitap listesini al

/kitaplar => PUT => Birden fazla kitap güncelle

/kitaplar => DELETE => Tüm kitapları sil

/kitaplar/1234 => POST => HATA mesajı dön

/kitaplar/1234 => GET => 1234 ID numaralı kitap detayları

/kitaplar/1234 => PUT => 1234 ID numaralı kitap bilgilerini güncelle

/kitaplar/1234 => DELETE => 1234 ID numaralı kitabı sil

* Kırmızı renkli yazılanlar HTTP Method isimleri elbette. 

Özet olarak;

  • Her kaynak için 2 kaynak URL kullanın
  • HTTP methodlarını servisi yönetmek için kullanın
  • URL yapılarında HTTP eylem kelimelerini kullanmaktan kaçının

 1.2 Kaynakların ilişkilendirilmesi

Bu bölüm biraz ustalık istesede, temiz ve basit tuttuğumuz sürece, fazla komplike olmadığını siz de göreceksiniz. Kaynakların ilişkilendirilmesi, servisimiz üzerinde bulunan birden fazla kaynağın ilişkisel olarak servise olarak sunulmasıdır. Örneğin; Kitaplar koleksiyonumuz üzerinden gidersek yine, belirli bir yazara ait olan kitapları listeleyen bir servis noktası oluşturmamız gerekebilir. Bu durumda klasik yöntemlerle gidersek;

/yazar/56787/kitaplar

gibi yeni bir servis noktası oluşturmamız gerekir. Fakat bizim kitaplar üzerinde işlem yaptığımız iki URL den oluşan bir kaynağımız zaten var. Bu durumda kullanıcılara kolaylık sağlamak, API servisimizi basit ve temiz tutmak adına, aynı kaynakları kullanabiliriz. Şöyleki;

/kaynak/tanımlayıcı/kaynak yerine ? işaretinin hünerlerini kullanabiliriz. Örnek olarak, bu koleksiyondaki, i.ari yazarına ait, romanlar içinde ankarada yayınlananları listeletmek istersek;

GET /kitaplar?yazar=i.ari&tur=roman&sehir=ankara

şeklinde aynı kaynağı kullanarak, kompleks bir APIden ziyade daha temiz bir API servisi elde etmiş oluruz.

Özet olarak, API mizde kaynakları ilişkilendirmek için temel kaynağımız üzerinden parametreler göndererek farklı sonuçlar alıp, API kaynaklarımızı sınırlı ve temiz tutabiliriz.

2. Hata yönetimi

Pek çok yazılım geliştiricisi, hata yönetimini çok fazla detaylandırmadan kullanır. Fakat API ler söz konusu olduğunda durum biraz daha farklı. API servisinizi kullanan developer açısından bakarsanız, servis adreslerinizin arkasındaki herşey, onlar için kapalı bir kutudur. Oluşan hata mesajlarını loglardan okuyamazlar. Bu durumda API üzerinden kullanıcıya döndüğümüz hata mesajlarının, gerek API dökümantasyonunda, gerekse de mesaj içeriği olarak geliştiriciyi yönlendirebilecek nitelikte olması gerekmektedir.

Pek çok yazılım geliştirici, programlama dillerini kitaplardan ziyade hata mesajlarını okuyarak ve “test ederek öğrenme” yolunu kullanarak öğrenirler. Bu da api servisinizi geliştirici için keşfedilecek bir ülke konumuna sokuyor.

Bir diğer neden de, yazılım geliştirici, kritik hatalarda, gerek development ortamında, gerekse de production ortamında, sorun çözümü için hata mesajlarınızı rehber olarak kullanacaktır.

Büyük API servislerini göz önünde tutarak, hata yönetimini nasıl ele aldıklarını inceleyelim.

Facebook
HTTP Status Code: 200
{“type” : “OauthException”, “message”:”(#803) Some of the
aliases you requested do not exist: foo.bar”}
Twilio
HTTP Status Code: 401
{“status” : “401”, “message”:”Authenticate”,”code”: 20003, “more
info”: “http://www.twilio.com/docs/errors/20003”}

Facebook API servisi üzerinde her ne olursa olsun, HTTP Status Code olarak 200 dönecektir. HTTP 200 herşey yolunda, bir sorun yok demektir. Facebook hata mesajını response body içinde tutuyor. bahsedilen #803 numaraları hata mesajını ancak Facebook API dökümantasyonunu okuyarak öğrenebiliriz.

Diğer taraftan Twilio API, Hata yönetimi konusunda çok başarılı bir iş çıkartıyor. Facebook gibi, response body içinde hata detaylarını , hata kodunu, ilgili dökümantasyon adresini vermekle beraber, HTTP Status code olarak da ilgili bir kod dönüyor (401; Authentication Required).

2.1 HTTP Durum kodlarını kullanın

Yaklaşık 70 tane HTTP durum kodu olmasına rağmen, çoğu yazılım geliştirici bunların pek çogunu ezbere bilmiyordur. bunun yerine üç basamaklı olan bu HTTP durum kodlarının genel anlamlarını bilmek, pratiklik sağlamaktadır. Örneğin 20x , 30x, 40x, 50x ..vs şeklinde gruplandırılabilen bu durum kodları ile ilgili detaylı bilgiyi w3 HTTP Status Codes  adresinden öğrenebilirsiniz.

Pek çok büyük API servisi, ortalama 10 durum koduyla tüm hata mesajlarını kullanıcılara iletmektedirler (size de daha fazlasının gerekli olacağını sanmıyorum, fakat her zaman farklı kodlara ihtiyacınız olabilir, o yüzden göz atmanızı öneririm).

Size önerim, 3 durum koduyla başlamanız, gerekli oldukça eklemeniz, fakat 6-7 farklı durum kodundan daha fazlasını kullanmamanız. Bu üç başlangıç kodu şu mantık üzerine kurulu olmalı;

  • Herşey yolunda – başarılı
  • Uygulama taraflı hata – kullanıcı hatası
  • API taraflı hata – sunucu hatası

Bu üçünü HTTP durum koduna çevirirsek;

  • 200 – OK
  • 400 – Bad Request
  • 500 – Internal Server Error

şeklinde olacaktır.

 

Diğer yazıda konuya devam edeceğim. Şimdilik bu kadar. Herkese kolay gelsin.

 

, , , , , ,