Revealed content
Başlamadan önce;
Makale içerisinde API geliştirken kullanacağımız ve zamanla aşina olacağınız bazı terimler olacak. Bunları bazen alışkanlıktan bazen de Türkçeye çevirdiğinizde anlamı tam karşılamadığından ingilizce olarak kullanmış olabilirim. O yüzden o terimlere kısaca listeleyecek olursam;
URL: En basit şekilde tanımlayacak olursak, bir web sitesine erişirken kullandığımız adres diyebiliriz. Oluşturduğunuz API'ın da bir adresi olur ve bu adres üzerinden ona erişir, diğer servislerle bağlarsınız.
Endpoint: API üzerinde belirli bir amaç için oluşturulmuş metodunuza verilen isim.
HTTP: Günümüz web teknolojisinde en yaygın kullanılan sunucu ve istemci arasındaki haberleşme protokolüdür. Genelde bir web sitesi üzerinde dolaşırken GET ve POST HTTP isteklerini yaygın olarak kullanırsınız fakat göreceksiniz ki API içerisinde farklı istek türleri de kullanılmakta.
İstek(HTTP Request); API üzerinde oluşturduğumuz çeşitli özellikteki endpoinlere, HTTP protokolü kullanarak yaptığınız taleplere denir.
Birçok dilde kendi API'ınızı yazıp, yine dil bağı olmadan istediğiniz dilde yazılmış uygulamalar, web siteleri, başka servisler ile entegre edebilirsiniz.
Restful olarak geliştirilmiş bir API üzerinden genellikle JSON tipinde dönüş yapılması tercih edilir fakat amaca ve isteğe göre XML, CSV, HTML veya düz bir metin olarak dönüş alabilirsiniz.
Restul API üzerinde HTTP protokünde yer alan çeşitli tipleri(GET,PUT,POST,DELETE) de etkin bir şekilde kullanıyoruz. Bu şekilde anlamlı URL'ler oluşturup göze ve programcıya hoş gelen linkler kolaylıkla oluşturuyoruz.
GET isteği yaptığımızda "Users" içerisinde 123 id'li kayıtı getirmesini istiyoruz, aynı endpointe DELETE isteği yaparsak da 123 id'li kullanıcıyı siliyoruz.
Kaynaklarda da yer verdiğim medium makalesi için bu konuyu özetleyen bir cümleye yer vermişler.
"The URL is a sentence, where resources are nouns and HTTP methods are verbs."
"URL'ler, HTTP metotlarının fiil ve kaynakların(controller ve sınıflarımız) isim olduğu cümlelerdir."
Bu yüzden API üzerinde oluşturduğumuz URL'leri mümkün olduğunca bir cümle olarak düşünmeliyiz.
HTTP istek türlerini ve kullanabilieceğimiz URL standartlarına makalenin devamında değineceğim. O yüzden makaleyi bitirdiğinizde nasıl bir URL oluşturmalıyım sorusuna cevabı kendiniz de veriyor olacaksınız.
Yine de uç noktayı merak edenlerdenseniz, 2000 karakter altında tutacağınız URL'lerde bir sorun yaşamazsınız fakat 2000 karakter üzerindeki URL'lerde tüm cihazlarda ve browserlarda çalıştıramayabilirsiniz. Daha ayrıntılı bilgi için bu linkten faydalı bir stackoverflow konusuna(ingilizce) erişebilirsiniz.
Request-Line: HTTP isteğin türü, hangi url'e yapılacağı ve http/https protokolü bilgisi
Header: Yapılan isteği niteleyen ve isteğe ait temel bilgileri içeren parametreleri taşır. Gönderilmesi zorunlu değildir, bir ve birden fazla header parametresi gönderebiliriz.
Body: Eğer POST,PUT,PATCH gibi API üzerinden bazı kayıt ve işlemler yapılmasını istiyorsak, bu bilgileri de isteğimizin Body alanında göndeririz. Restful bir API'da JSON olarak bu bilgileri gönderilmesi tercih edilir.
Kullandığınız bowser'ın geliştici seçenekleri(F12) içerisinde Network tab'I altında arkaplanda yapılan istekleri inceleyebilirsiniz. Örneğin bu siteye girerken yaptığınız bir anasayfa isteği aşağıdaki gibidir;
API'larımızda hem anlamlı URL'ler oluşturmak hem de karmaşıklığı daha aza indirmek için yaygın kullanılan HTTP istek türleri olarak aşağıdakileri sayabilirim;
GET: Veri çekmek için kullanılır.
POST:Yeni bir kayıt oluşturmak için kullanılır.
PUT: Varolan bir kayıtı güncellemek için kullanılır.
PATCH: Varolan bir kayıtta belirli bir parça üzerinde güncelleme yapılacaksa kullanılabilir. Bu işlem istek yerine tüm güncellemeler için PUT kullanımı da yaygındır.
DELETE: Varolan bir kayıtı silmek için kullanılır.
Header için kullanılan standart parametreler vardır. Culture, Content-Type, Authentication bunlardan bazılarıdır. Bunları göndermemiz zorunlu değildir ama iyi bir API için ihtiyacınız olacaktır.
Header üzerinde kullanılan standartları buradan detaylı bir şekilde inceyelebilirsiniz.
Ayrıca bu listedekiler dışında kendi istediğiniz isimde bir header adı oluşturup onu da sunucuya yaptığınız istekte gönderebilirsiniz. Bunu yaparken sunucunun da bu header değerini aynı isimde aldığından emin olmanız gerekmektedir.
JSON günümüzde sunucular arasında haberleşme yapmak ve aynı zamanda ufak boyutta taşınabilmesinden ötürü oluşturulmuştur. XML standardına alternatif olarak oluşturulmuştur. Düzenli veri saklamak için de JSON formatında dosyalar oluşturulup burada anlamlı modeller oluşturulabilir.
JSON içerisinde bir anahtar(key) ve o anahtara ait değer(value) içerir.
JSON yapıları ile ilgili daha ayrıntılı bilgi için bakabilirsiniz(1, 2)
Elimden geldiğince Türkçe kelimeler kullanmaya çalıştım fakat kullandığımız URL yapısında ingilizce isimlendirmeler tercih edilmeli. URL'de kullanacağınız türkçe karakterlerde çeşitli uyum sorunları yaşayabilirsiniz. Bu yüzden ben de makalenin geri kalanında anlatacağım URL formatında Users (Kullanıcılar) endpointi üzerinden ilerleyeceğim.
1. Bir API yaparken aynı sınıfa ait işlemleri bir grup altına toplamalıyız. Örneğin API üzerinden kullanıcılara ait erişmek ve işlem yapmak istediğimizde hepsini "Users" url'i üzerinden yapmalıyız.
2. Bir sınıfı temsil eden veya belirli bir amaç için grupladığımız bu endpointleri, çoğul isimle oluşturmalıyız.
Örneğin;
olarak isimlendirmeyi yapmalıyız.
3. Oluşturduğumuz endpointin doğrudan kendisine atacağımız GET isteklerinde o sınıfa ait tüm listeyi dönmeliyiz.
Örneğin;
4. Bir sınıfa ait tek bir kayıta ulaşmak istediğimizde onun ait olduğu sınıfa, onu temsil eden benzersiz(unique) id değeri ile istek atmalıyız ve karşılığında bize o sınıfa ait bilgileri dönmeliyiz.
Örneğin;
5. Bir sınıfa ait yeni bir kayıt oluşturmak istediğmizde doğrudan onun sınıfına POST isteği ile beraber body içerisinde bu yeni bilgileri göndermeliyiz.
Örneğin;
6. Bir sınıfa ait kayıtı silmek istediğimizde, ona ait id değeri ile DELETE isteği attığımızda silmeliyiz.
Örneğin;
7. Bir sınıfa ait kayıtta, ona bağlı diğer sınıflara erişmek istediğinizde, yani bir Users altında User kayıtının bildirimlerine(notifications) ulaşmak istediğinizde aşağıdakine benzer sıralı bir URL altında dönebilirsiniz.
Böylelikle url'e baktığınızda kolayca ne iş yaptığını anlayabiliyorsunuz.
kullanıcılardan -> 2 id'li kullanıcının -> bildirimlerini GET(getir)
Buraya kadar bir isteği nasıl yapacağımızı öğrendik. Şimdi sıra talepte bulunan istemcilere(client) cevabı vermekte.
Status-line; kendi içerisinde HTTP protokolü, http status kodu ve status mesajı yer alır. Örneğin;"HTTP/1.1 404 Not Found"
Header; Gönderdiğimiz HTTP Requestin header bilgisi olduğu gibi bize dönen cevabın da header'I olabilir.
Body; Tüm isteklerde olmasa da bir model almak istediğmizde veya sunucudan bir cevap bekledğimizde buradn talep ettiğimiz veriye ulaşırız. API'da dönen JSON modeli buradan okuruz.
Makale içerisinde API geliştirken kullanacağımız ve zamanla aşina olacağınız bazı terimler olacak. Bunları bazen alışkanlıktan bazen de Türkçeye çevirdiğinizde anlamı tam karşılamadığından ingilizce olarak kullanmış olabilirim. O yüzden o terimlere kısaca listeleyecek olursam;
URL: En basit şekilde tanımlayacak olursak, bir web sitesine erişirken kullandığımız adres diyebiliriz. Oluşturduğunuz API'ın da bir adresi olur ve bu adres üzerinden ona erişir, diğer servislerle bağlarsınız.
Endpoint: API üzerinde belirli bir amaç için oluşturulmuş metodunuza verilen isim.
HTTP: Günümüz web teknolojisinde en yaygın kullanılan sunucu ve istemci arasındaki haberleşme protokolüdür. Genelde bir web sitesi üzerinde dolaşırken GET ve POST HTTP isteklerini yaygın olarak kullanırsınız fakat göreceksiniz ki API içerisinde farklı istek türleri de kullanılmakta.
İstek(HTTP Request); API üzerinde oluşturduğumuz çeşitli özellikteki endpoinlere, HTTP protokolü kullanarak yaptığınız taleplere denir.
RESTful API Nedir?
API'ların ne olduğuna bu makalemizde anlatmıştık. Rest de temelinde HTTP protokolü üzerinden haberleşen bir mimari yaklaşımdır. Bu mimari yaklaşımı kullanan API'lara da Restful API olarak adlandırıyoruz. Restful standardı daha eski ve katı kuralları olan SOAP servislere bir çözüm olarak geliştirilmiş ve tercih edilmiştir.Birçok dilde kendi API'ınızı yazıp, yine dil bağı olmadan istediğiniz dilde yazılmış uygulamalar, web siteleri, başka servisler ile entegre edebilirsiniz.
Restful olarak geliştirilmiş bir API üzerinden genellikle JSON tipinde dönüş yapılması tercih edilir fakat amaca ve isteğe göre XML, CSV, HTML veya düz bir metin olarak dönüş alabilirsiniz.
Restul API üzerinde HTTP protokünde yer alan çeşitli tipleri(GET,PUT,POST,DELETE) de etkin bir şekilde kullanıyoruz. Bu şekilde anlamlı URL'ler oluşturup göze ve programcıya hoş gelen linkler kolaylıkla oluşturuyoruz.
RESTful URL Yapısı nasıl olmalı?
Oluşturduğumuz url'leri başka bir yazılımcı, hatta bir analist baktığında kolayca anlayabilmelidir. Karmaşık isimlendirmeler ve url üzerine eklenecek gereksiz parametrelerden kaçınmalıyız. Örneğin aşağıdaki endpointi incelediğimizde;GET isteği yaptığımızda "Users" içerisinde 123 id'li kayıtı getirmesini istiyoruz, aynı endpointe DELETE isteği yaparsak da 123 id'li kullanıcıyı siliyoruz.
Kaynaklarda da yer verdiğim medium makalesi için bu konuyu özetleyen bir cümleye yer vermişler.
"The URL is a sentence, where resources are nouns and HTTP methods are verbs."
"URL'ler, HTTP metotlarının fiil ve kaynakların(controller ve sınıflarımız) isim olduğu cümlelerdir."
Bu yüzden API üzerinde oluşturduğumuz URL'leri mümkün olduğunca bir cümle olarak düşünmeliyiz.
HTTP istek türlerini ve kullanabilieceğimiz URL standartlarına makalenin devamında değineceğim. O yüzden makaleyi bitirdiğinizde nasıl bir URL oluşturmalıyım sorusuna cevabı kendiniz de veriyor olacaksınız.
URL Uzunluğu Ne Olmalı?
Bir URL nasıl olmalı sorusuna verdiğimiz cevap okunur olmasıydı. Fakat fazla uzun url'ler de bir yerden sonra takip edilmesi zor bir hal alacaktır. Bunun için imkan oldukça kısa ve anlamlı tutulmalıdır.Yine de uç noktayı merak edenlerdenseniz, 2000 karakter altında tutacağınız URL'lerde bir sorun yaşamazsınız fakat 2000 karakter üzerindeki URL'lerde tüm cihazlarda ve browserlarda çalıştıramayabilirsiniz. Daha ayrıntılı bilgi için bu linkten faydalı bir stackoverflow konusuna(ingilizce) erişebilirsiniz.
Bir HTTP Request(isteği) nelerden oluşur?
En yalın haliyle bir HTTP isteğini aşağıdaki bilgileri taşır;Request-Line: HTTP isteğin türü, hangi url'e yapılacağı ve http/https protokolü bilgisi
Header: Yapılan isteği niteleyen ve isteğe ait temel bilgileri içeren parametreleri taşır. Gönderilmesi zorunlu değildir, bir ve birden fazla header parametresi gönderebiliriz.
Body: Eğer POST,PUT,PATCH gibi API üzerinden bazı kayıt ve işlemler yapılmasını istiyorsak, bu bilgileri de isteğimizin Body alanında göndeririz. Restful bir API'da JSON olarak bu bilgileri gönderilmesi tercih edilir.
Kullandığınız bowser'ın geliştici seçenekleri(F12) içerisinde Network tab'I altında arkaplanda yapılan istekleri inceleyebilirsiniz. Örneğin bu siteye girerken yaptığınız bir anasayfa isteği aşağıdaki gibidir;
HTTP Request(istek) Türleri Neler?
Biz bir adrese istek yaparken o isteğin türünü de belirtiriz. Örneğin browser üzerinden bir web sitesine gittiğinizde, o adrese erişmek istediğimizi browser'ımız karşı sunucuya GET(getir) isteği yaparak belirtir ve kaynak sunucu bize o sitenin html cevabıyla dönüş yapar. Bir üyelik formu doldururken kaydet dediğinizde browser'ınız kaynak sunucuya sizin girdiğiniz bilgiler ile beraber bir POST(gönder, postala) isteği yapar.API'larımızda hem anlamlı URL'ler oluşturmak hem de karmaşıklığı daha aza indirmek için yaygın kullanılan HTTP istek türleri olarak aşağıdakileri sayabilirim;
GET: Veri çekmek için kullanılır.
POST:Yeni bir kayıt oluşturmak için kullanılır.
PUT: Varolan bir kayıtı güncellemek için kullanılır.
PATCH: Varolan bir kayıtta belirli bir parça üzerinde güncelleme yapılacaksa kullanılabilir. Bu işlem istek yerine tüm güncellemeler için PUT kullanımı da yaygındır.
DELETE: Varolan bir kayıtı silmek için kullanılır.
Header Nedir?
Yaptığımız isteğe ait temel bilgileri de sunucuya iletmemiz gerekebilir. Bu isteği yaptığımız sunucu bu isteği açmadan önce Header içerisinde yer alan bilgileri işleyip ona göre iç akışına devam eder. Örneğin dil(culture) bilgisini header üzerinde taşıyıp sunucunun bizim isteğimizi işlerken hangi dile göre hareket edeceğini bilmesini sağlarız. Bir diğer örnek olarak sadece üye olan kullanıcıların erişebildiği bir API yapmış ve yetkisi olmayan kişilerin istek yapmasını engellemek isteriz. Bunun için de yaptığımız isteklerde Authentication parametresiyle beraber anahtar bilgisini(token) sunucuya iletip önce bu bilgiyi kontrol etmesini ve sadece yetkisi olan kişilerin API içerisine erişebilmesini sağlarız.Header için kullanılan standart parametreler vardır. Culture, Content-Type, Authentication bunlardan bazılarıdır. Bunları göndermemiz zorunlu değildir ama iyi bir API için ihtiyacınız olacaktır.
Header üzerinde kullanılan standartları buradan detaylı bir şekilde inceyelebilirsiniz.
Ayrıca bu listedekiler dışında kendi istediğiniz isimde bir header adı oluşturup onu da sunucuya yaptığınız istekte gönderebilirsiniz. Bunu yaparken sunucunun da bu header değerini aynı isimde aldığından emin olmanız gerekmektedir.
JSON nedir?
JSON günümüzde sunucular arasında haberleşme yapmak ve aynı zamanda ufak boyutta taşınabilmesinden ötürü oluşturulmuştur. XML standardına alternatif olarak oluşturulmuştur. Düzenli veri saklamak için de JSON formatında dosyalar oluşturulup burada anlamlı modeller oluşturulabilir.JSON içerisinde bir anahtar(key) ve o anahtara ait değer(value) içerir.
JSON yapıları ile ilgili daha ayrıntılı bilgi için bakabilirsiniz(1, 2)
Elimden geldiğince Türkçe kelimeler kullanmaya çalıştım fakat kullandığımız URL yapısında ingilizce isimlendirmeler tercih edilmeli. URL'de kullanacağınız türkçe karakterlerde çeşitli uyum sorunları yaşayabilirsiniz. Bu yüzden ben de makalenin geri kalanında anlatacağım URL formatında Users (Kullanıcılar) endpointi üzerinden ilerleyeceğim.
Restful API Standartları Neler?
Burada sıralayacağım maddeler zorunlu kurallar değildir fakat bir Restful API geliştirilirken uyulması tercih edilen, kabul görmüş kalıplardır;1. Bir API yaparken aynı sınıfa ait işlemleri bir grup altına toplamalıyız. Örneğin API üzerinden kullanıcılara ait erişmek ve işlem yapmak istediğimizde hepsini "Users" url'i üzerinden yapmalıyız.
2. Bir sınıfı temsil eden veya belirli bir amaç için grupladığımız bu endpointleri, çoğul isimle oluşturmalıyız.
Örneğin;
| 1 2 | api.caylakyazilimci.com/company yerine api.caylakyazilimci.com/companies api.caylakyazilimci.com/user yerine api.caylakyazilimci.com/users |
3. Oluşturduğumuz endpointin doğrudan kendisine atacağımız GET isteklerinde o sınıfa ait tüm listeyi dönmeliyiz.
Örneğin;
| 1 2 | api.caylakyazilimci.com/users api.caylakyazilimci.com/companies |
Örneğin;
| 1 2 | api.caylakyazilimci.com/users /1 api.caylakyazilimci.com/users /CFAF1A94-91D6-4413-9320-7DD7157A2E54 |
Örneğin;
| 1 | api.caylakyazilimci.com/users |
Örneğin;
| 1 2 | api.caylakyazilimci.com/users /5 api.caylakyazilimci.com/users /CFAF1A94-91D6-4413-9320-7DD7157A2E54 |
| 1 | api.caylakyazilimci.com/users /2/notifications |
kullanıcılardan -> 2 id'li kullanıcının -> bildirimlerini GET(getir)
Buraya kadar bir isteği nasıl yapacağımızı öğrendik. Şimdi sıra talepte bulunan istemcilere(client) cevabı vermekte.
HTTP Response(cevap) nelerden oluşur?
Her HTTP Request'in bir yapısı olduğu gibi, döndüğümüz cevabın da belirli bir yapısı vardır. İstekte bulunan kullanıcılar sunucudan yanıtını aldığında bu cevap üzerindeki parametrelerden kendi aksiyonlarını alabilir. Basit bir haliyle bir HTTP Response aşağıdaki yapıdan oluşur;Status-line; kendi içerisinde HTTP protokolü, http status kodu ve status mesajı yer alır. Örneğin;"HTTP/1.1 404 Not Found"
Header; Gönderdiğimiz HTTP Requestin header bilgisi olduğu gibi bize dönen cevabın da header'I olabilir.
Body; Tüm isteklerde olmasa da bir model almak istediğmizde veya sunucudan bir cevap bekledğimizde buradn talep ettiğimiz veriye ulaşırız. API'da dönen JSON modeli buradan okuruz.
Bu içeriği görmek için giriş yapın.
