REST API'lerini Anlama ve Kullanma

Twitter veya Github gibi internetteki başka bir kaynaktan veri almayı düşündüyseniz, “REST API” terimiyle karşılaşma olasılığınız yüksektir. Ancak REST API nedir? Senin için ne yapabilir? Nasıl kullanıyorsun?

Bu makalede, API belgelerini okuyabilmek ve etkin bir şekilde kullanabilmek için REST API'leri hakkında bilmeniz gereken her şeyi öğreneceksiniz.

REST API Nedir?

Diyelim ki Youtube'da Batman ile ilgili videolar bulmaya çalışıyorsunuz. Youtube'u açıyorsunuz, arama alanına “Batman” yazıp enter tuşuna basıyorsunuz ve Batman ile ilgili videoların bir listesini görüyorsunuz. Bir REST API benzer şekilde çalışır. Bir şey ararsınız ve talep ettiğiniz hizmetten bir sonuç listesi alırsınız.

API , bir uygulama programlama arabirimidir. Programların birbirleriyle konuşmasını sağlayan bir dizi kuraldır. Geliştirici, API'yi sunucuda oluşturur ve istemcinin onunla konuşmasına izin verir.

REST , API'nin nasıl göründüğünü belirler. “Temsili Devlet Transferi” anlamına gelir. Geliştiricilerin API'lerini oluştururken izledikleri bir dizi kuraldır. Bu kurallardan biri, belirli bir URL'ye bağlandığınızda bir parça veri (kaynak adı verilir) alabilmeniz gerektiğini belirtir.

Her URL'ye istek , size geri gönderilen verilere yanıt adı verilir.

Bir İsteğin Anatomisi

Bir talebin dört şeyden oluştuğunu bilmek önemlidir:

1. uç nokta
2. yöntem
3. başlıklar
4. Veri (veya gövde)

Uç nokta (veya rota), talep ettiğiniz url'dir. Bu yapıyı takip eder:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

Kök uç noktası, talep ettiğiniz API'nin başlangıç ​​noktasıdır. Github API'sinin kök uç noktası https://api.github.com iken kök uç nokta Twitter'ın API'si https://api.twitter.com ://api.twitter.com'dur.

Yol , talep ettiğiniz kaynağı belirler. Bunu bir servis için 1'e, başka bir servis için 2'ye, başka bir servis için 3'e vs. basmanızı isteyen otomatik bir telesekreter gibi düşünün.

Yollara tıpkı bir web sitesinin bölümlerine bağladığınız gibi erişebilirsiniz. Örneğin, Smashing Magazine'de "JavaScript" altında etiketlenen tüm gönderilerin bir listesini almak için https://www.smashingmagazine.com/tag/javascript/ gidin. https://www.smashingmagazine.com/ kök uç noktadır ve /tag/javascript yoldur.

Kullanabileceğiniz yolları anlamak için API belgelerine bakmanız gerekir. Örneğin, Github'un API'si aracılığıyla belirli bir kullanıcı tarafından depoların bir listesini almak istediğinizi varsayalım. Dokümanlar, bunu yapmak için aşağıdaki yolu kullanmanızı söyler:

 /users/:username/repos

Bir yol üzerindeki herhangi bir iki nokta üst üste ( : ) bir değişkeni belirtir. Bu değerleri, isteğinizi gönderdiğinizde gerçek değerlerle değiştirmelisiniz. Bu durumda, :username öğesini aradığınız kullanıcının gerçek kullanıcı adıyla değiştirmelisiniz. Github hesabımı arıyorsam, :username ile zellwk değiştireceğim.

Github'daki depolarımın bir listesini almak için son nokta şudur:

 https://api.github.com/users/zellwk/repos

Bir uç noktanın son kısmı, sorgu parametreleridir . Teknik olarak, sorgu parametreleri REST mimarisinin bir parçası değildir, ancak birçok API'nin bunları kullandığını göreceksiniz. Bu nedenle, API'leri nasıl okuyacağınızı ve kullanacağınızı tamamen anlamanıza yardımcı olmak için onlardan da bahsedeceğiz. Sorgu parametreleri, isteğinizi anahtar/değer çiftleriyle değiştirme seçeneği sunar. Her zaman bir soru işareti ( ? ) ile başlarlar. Her parametre çifti daha sonra ve işaretiyle ( & ) ayrılır, şöyle:

 ?query1=value1&query2=value2

Github'da bir kullanıcının depolarının bir listesini almaya çalıştığınızda, size verilen sonuçları değiştirmek için isteğinize üç olası parametre eklersiniz:

Son zamanlarda ittiğim depoların bir listesini almak isterseniz, sort push olarak ayarlayabilirsiniz.

 https://api.github.com/users/zellwk/repos?sort=pushed

Bu son noktanın işe yarayıp yaramadığını nasıl anlarsınız? Peki, denemenin zamanı geldi!

Curl ile Uç Noktaları Test Etme

Herhangi bir programlama dili ile istek gönderebilirsiniz. JavaScript kullanıcıları, Fetch API ve jQuery'nin Ajax yöntemi gibi yöntemleri kullanabilir; Ruby kullanıcıları Ruby'nin Net::HTTP sınıfını kullanabilir, Python kullanıcıları Python İsteklerini kullanabilir; ve bunun gibi.

Bu makale için cURL adlı komut satırı yardımcı programını kullanacağız. API belgeleri normalde cURL referans alınarak yazıldığından cURL kullanıyoruz. cURL'yi nasıl kullanacağınızı anlarsanız, API belgelerini anlamakta sorun yaşamazsınız. Ardından, tercih ettiğiniz dil ile istekleri kolayca gerçekleştirebilirsiniz.

Devam etmeden önce, makinenizde cURL'nin kurulu olduğundan emin olmak isteyeceksiniz. Terminalinizi açın ve curl -version . Bu komut, sisteminize kurduğunuz cURL sürümünü kontrol eder.

 curl --version

Eğer cURL kurulu değilse, "komut bulunamadı" hatası alırsınız. Bu hatayı alırsanız, devam etmeden önce curl yüklemeniz gerekecektir.

cURL'yi kullanmak için curl ve ardından istediğiniz bitiş noktasını yazarsınız. Örneğin, Github'ın kök uç noktasını almak için aşağıdakini yazarsınız:

 curl https://api.github.com

Enter'a bastığınızda, Github'dan şuna benzeyen bir yanıt almalısınız:

Bir kullanıcının depolarının bir listesini almak için, yukarıda tartıştığımız gibi uç noktayı doğru yola değiştirirsiniz. Depolarımın bir listesini almak için bu komutu kullanabilirsiniz:

 curl https://api.github.com/users/zellwk/repos

\ ile sorgu parametrelerini dahil etmek istiyorsanız, ? ve = karakterler. Bunun nedeni ? ve = komut satırındaki özel karakterlerdir. Komut satırının bunları normal karakterler olarak yorumlaması için onlardan önce \ kullanmanız gerekir:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

Komutlardan birini kullanmayı deneyin ve bir istek gerçekleştirin! Github'ın kök uç noktası ile gördüklerinize benzer bir yanıt alacaksınız (ancak çok daha fazla veri ile).

JSON

JSON (JavaScript Object Notation), bir REST API aracılığıyla veri göndermek ve istemek için yaygın bir biçimdir. Github'un size geri gönderdiği yanıt da JSON olarak biçimlendirilir.

Bir JSON nesnesi, bir JavaScript Nesnesi gibi görünür. JSON'da her özellik ve değer, aşağıdaki gibi çift tırnak içine alınmalıdır:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

Bir İsteğin Anatomisine Geri Dön

Bir isteğin dört bölümden oluştuğunu öğrendiniz.

1. uç nokta
2. yöntem
3. başlıklar
4. Veri (veya gövde)

Bir istek oluşturan geri kalanı üzerinden gidelim.

Yöntem

Yöntem, sunucuya gönderdiğiniz istek türüdür. Aşağıdaki beş tür arasından seçim yapabilirsiniz:

• GET
• POST
• PUT
• PATCH
• DELETE

Bu yöntemler, yaptığınız istek için anlam sağlar. Dört olası eylemi gerçekleştirmek için kullanılırlar: Create , Read , Update ve Delete (CRUD).

API, her bir isteğin hangi istek yöntemini kullanacağını bilmenizi sağlar. Örneğin, bir kullanıcının depolarının bir listesini almak için bir GET isteğine ihtiyacınız vardır:

Bir kullanıcıdan depoların bir listesini almak için bir GET isteği gereklidir. Yeni bir Github deposu oluşturmak için bir POST isteğine ihtiyacınız var:

İstek yöntemini cURL'de -X veya --request ardından istek yöntemini yazarak ayarlayabilirsiniz. Aşağıdaki komut, cURL aracılığıyla bir havuz oluşturmaya çalışır:

 curl -X POST https://api.github.com/user/repos

Bu isteği çalıştırmayı deneyin. Kimlik doğrulamanın gerekli olduğunu söyleyen bir yanıt alacaksınız. (Daha sonra kimlik doğrulama hakkında daha fazla bilgi).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Başlıklar

Başlıklar hem istemciye hem de sunucuya bilgi sağlamak için kullanılır. Kimlik doğrulama ve gövde içeriği hakkında bilgi sağlama gibi birçok amaç için kullanılabilir. Geçerli başlıkların bir listesini MDN'nin HTTP Başlıkları Referansında bulabilirsiniz.

HTTP Başlıkları, iki nokta üst üste ile ayrılmış özellik-değer çiftleridir . Aşağıdaki örnek, sunucuya JSON içeriği beklemesini söyleyen bir başlığı göstermektedir.

 "Content-Type: application/json". Missing the opening ".

-H veya --header seçeneği ile HTTP başlıklarını curl ile gönderebilirsiniz. Yukarıdaki başlığı Github'ın API'sine göndermek için şu komutu kullanırsınız:

 curl -H "Content-Type: application/json" https://api.github.com

(Not: Github API'sinin çalışması için Content-Type başlığı bir gereklilik değildir. Bu sadece bir başlığın cURL ile nasıl kullanılacağını gösteren bir örnektir).

Gönderdiğiniz başlıkları görüntülemek için, isteği gönderirken -v veya --verbose seçeneğini şu şekilde kullanabilirsiniz:

 curl -H "Content-Type: application/json" https://api.github.com -v 

Burada * , cURL tarafından sağlanan ek bilgileri ifade eder. > istek başlıklarını ifade eder ve < yanıt başlıklarını ifade eder.

Veriler (Veya “Gövde”)

Veriler (bazen "gövde" veya "mesaj" olarak adlandırılır) sunucuya gönderilmesini istediğiniz bilgileri içerir. Bu seçenek yalnızca POST , PUT , PATCH veya DELETE istekleriyle kullanılır.

cURL aracılığıyla veri göndermek için -d veya --data seçeneğini kullanabilirsiniz:

 curl -X POST <URL> -d property1=value1

Birden çok veri alanı göndermek için birden çok -d seçeneği oluşturabilirsiniz:

 curl -X POST <URL> -d property1=value1 -d property2=value2

Mantıklıysa, okumayı kolaylaştırmak için isteğinizi birden çok satıra bölebilirsiniz \ :

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Bir sunucuyu nasıl çalıştıracağınızı biliyorsanız, bir API yapabilir ve kendi verilerinizi test edebilirsiniz. Bilmiyorsanız ancak deneyecek kadar cesaretli hissediyorsanız Node, Express ve MongoDB ile sunucu oluşturmayı öğrenmek için bu makaleyi takip edebilirsiniz.

Sunucunuzu hızlandırmak istemiyorsanız, Requestbin.com'a ( ücretsizdir! ) gidebilir ve “endpoint oluştur”a tıklayabilirsiniz. Aşağıdaki resimde gösterilen https://requestb.in/1ix963n1 gibi, istekleri test etmek için kullanabileceğiniz bir URL verilecektir.

İsteğinizi test etmek istiyorsanız, kendi istek kutunuzu oluşturduğunuzdan emin olun. İstek kutuları, oluşturulduktan sonra yalnızca 48 saat açık kalır. Bu makaleyi okuduğunuzda, yukarıda oluşturduğum çöp kutusu çoktan gitmiş olacak.

Şimdi, istek kutunuza biraz veri göndermeyi deneyin, ardından kutunuzun web sayfasını yenileyin. Bunun gibi bazı veriler göreceksiniz:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

Varsayılan olarak cURL, verileri bir sayfadaki "form alanları" aracılığıyla gönderilmiş gibi gönderir. JSON verilerini göndermek istiyorsanız, Content-Type application/json olarak ayarlamanız ve verilerinizi aşağıdaki gibi bir JSON nesnesi olarak biçimlendirmeniz gerekir:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

Ve bu (neredeyse!) bir talebin yapısı hakkında bilmeniz gereken her şey.

Şimdi, Github'un API'si aracılığıyla bir POST isteği göndermeye çalıştığınızda, “Kimlik doğrulama gerektirir” yazan bir mesajınız olduğunu hatırlıyor musunuz? Bunun nedeni, POST isteğini gerçekleştirme yetkiniz olmamasıdır!

kimlik doğrulama

İzniniz olmadan kimsenin banka hesabınıza erişmesine izin vermezsiniz, değil mi? Aynı düşünce doğrultusunda geliştiriciler, eylemleri yalnızca yetkiniz olduğunda gerçekleştirmenizi sağlamak için önlemler alır. Bu, başkalarının sizi taklit etmesini engeller.

POST , PUT , PATCH ve DELETE istekleri veritabanını değiştirdiğinden, geliştiriciler onları neredeyse her zaman bir kimlik doğrulama duvarının arkasına koyar. Bazı durumlarda, bir GET isteği ayrıca kimlik doğrulama gerektirir (örneğin, mevcut bakiyenizi kontrol etmek için banka hesabınıza eriştiğinizde).

Web'de, kendinizi doğrulamanın iki ana yolu vardır:

1. Bir kullanıcı adı ve parola ile (temel kimlik doğrulama da denir)
2. Gizli bir jeton ile

Gizli belirteç yöntemi, Github, Google, Twitter, Facebook vb. gibi sosyal medya ağlarında kimliğinizi doğrulamanıza izin veren oAuth'u içerir.

Bu makale için, yalnızca bir kullanıcı adı ve parolayla temel kimlik doğrulamayı kullanmayı öğreneceksiniz. oAuth ile kimlik doğrulamayla ilgileniyorsanız, Zack Grossbart'ın “OAuth2 ve Facebook ile Oturum Açma Hakkında Bilmeniz Gerekenler” başlıklı makalesini okumanızı öneririm.

CURL ile temel bir kimlik doğrulaması gerçekleştirmek için -u seçeneğini, ardından kullanıcı adınızı ve şifrenizi aşağıdaki gibi kullanabilirsiniz:

 curl -x POST -u "username:password" https://api.github.com/user/repos

Yukarıdaki istekte kullanıcı adınız ve şifrenizle kimliğinizi doğrulamayı deneyin. Kimlik doğrulamada başarılı olduğunuzda, yanıtın "Kimlik doğrulama gerektirir"den "JSON ayrıştırma sorunları"na değiştiğini göreceksiniz.

Bunun nedeni, sunucuya henüz herhangi bir veri sağlamamış olmanızdır (tüm POST , PUT , PATCH ve DELETE istekleri için gereklidir).

Şimdiye kadar öğrendiğiniz bilgilerle, cURL'niz aracılığıyla bir Github deposu oluşturmak için yukarıdaki kodu düzenleyebilmelisiniz. Kendin denemen için seni bırakıyorum!

Şimdi biraz HTTP Durum kodlarından ve hata mesajlarından bahsedelim.

HTTP Durum Kodları ve Hata Mesajları

"Kimlik doğrulama gerektirir" ve "JSON ayrıştırma sorunları" gibi daha önce aldığınız mesajlardan bazıları hata mesajlarıdır. Yalnızca isteğinizle ilgili bir sorun olduğunda görünürler. HTTP durum kodları, yanıtın durumunu hızlı bir şekilde söylemenizi sağlar. 100+ ile 500+ arasında değişir. Genel olarak, sayılar aşağıdaki kurallara uyar:

1. 200+ , isteğin başarılı olduğu anlamına gelir.
2. 300+ , isteğin başka bir URL'ye yönlendirildiği anlamına gelir
3. 400+ , istemciden kaynaklanan bir hatanın oluştuğu anlamına gelir
4. 500+ , sunucudan kaynaklanan bir hatanın oluştuğu anlamına gelir

Ayrıntılı seçeneği ( -v veya --verbose ) veya head seçeneği ( -I veya --head ) ile bir yanıtın durumunda hata ayıklayabilirsiniz.

Örneğin, kullanıcı adınızı ve şifrenizi girmeden bir POST isteğine -I eklemeyi denediyseniz, bir 401 durum kodu alırsınız (Yetkisiz):

Verileriniz yanlış veya eksik olduğu için talebiniz geçersizse, genellikle 400 durum kodu (Kötü İstek) alırsınız.

Belirli HTTP durum kodları hakkında daha fazla bilgi almak için MDN'nin HTTP Durum Referansına bakmak isteyebilirsiniz.

API Sürümleri

Geliştiriciler, API'lerini zaman zaman günceller. Bazen API o kadar çok değişebilir ki geliştirici API'sini başka bir sürüme yükseltmeye karar verir. Bu olursa ve uygulamanız bozulursa, bunun nedeni genellikle daha eski bir API için kod yazmış olmanızdır, ancak isteğiniz daha yeni API'yi işaret etmektedir.

Belirli bir API sürümünü iki şekilde talep edebilirsiniz. Hangi yolu seçeceğiniz, API'nin nasıl yazıldığına bağlıdır.

Bu iki yol:

1. Doğrudan uç noktada
2. Bir istek başlığında

Örneğin Twitter ilk yöntemi kullanır. Yazma sırasında, Twitter'ın API'si, uç noktasından açıkça görülen 1.1 sürümündedir:

 https://api.twitter.com/1.1/account/settings.json

Github ise ikinci yöntemi kullanır. Yazma sırasında, Github'ın API'si sürüm 3'tedir ve sürümü bir Accept başlığıyla belirtebilirsiniz:

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Toplama

Bu yazıda REST API'nin ne olduğunu ve GET , POST , PUT , PATCH ve DELETE yöntemleriyle istek gerçekleştirmek için cURL'nin nasıl kullanılacağını öğrendiniz. Ayrıca -u seçeneğiyle isteklerinizin kimliğini nasıl doğrulayacağınızı ve HTTP durumlarının ne anlama geldiğini de öğrendiniz.

Umarım bu makale, REST API'leri hakkında yeterince bilgi edinmenize yardımcı olmuştur ve uygulamalarınızı oluştururken bunları akıcı bir şekilde kullanabilirsiniz. Herhangi bir sorunuz varsa, bloguma uğrayabilir veya yorumlarınızı aşağıya bırakabilirsiniz.