Bu Yazıda API (Application Programming Interface) Nedir, CRUD (Create, Read, Update, Delete) İşlemleri, HTTP Metotları (HTTP Verbs), HTTP Durum Kodları ve REST API Hakkında Bilgi Edinip Cisco DevNet Platformu ve Postman Programını Kullanarak Cisco DNA Center REST API Call Örneği Yapacağız.
CRUD; Create, Read, Update, Delete Anlamına Gelir ve REST API Kullanırken Gerçekleştirdiğimiz İşlemleri İfade Eder. HTTP Verbs, CRUD İşlemleri için Kullanılır.
Bu Yazıdan Önce Network Automation ve JSON, XML & YAML Yazılarını okumanızı Tavsiye Ederim.
API (Application Programming Interface)
- İki Uygulamanın Birbiri ile İletişim Kurmasını Sağlayan Yazılım Arayüzüdür.
- API, Yalnızca Ağ Otomasyonu için Değil, Her Türlü Uygulama için Gereklidir. Diğer Uygulamaların Uygulamanızdaki Verilere Erişmesini İstiyorsanız Bir API Tasarlamanız Gerekir.
- SDN Mimarisini Hatırlayalım.
- SDN Mimarisinde API, Uygulama (App) ve SDN Controller (NBI Aracılığıyla) ve SDN Controller ile Ağ Cihazları (SBI Aracılığıyla) Arasında İletişim Kurmak için Kullanılır.
- NBI Genellikle REST API Kullanır.
- NETCONF ve RESTCONF, Popüler SBI API'leridir.
CRUD (Create, Read, Update, Delete)
REST API Kullanarak Gerçekleştirdiğimiz İşlemleri İfade Eder.
Create
- Yeni Değişkenler Oluşturmak ve Başlangıç Değerlerini Ayarlamak için Kullanılır.
- Örnek: create variable "ip_address" and set the value to "10.1.1.1".
Read
- Değişkenin Değerini Almak için Kullanılır.
- Örnek: What is the Value of Variable "ip_address"?
Update
- Değişkenin Değerini Değiştirmek için Kullanılır.
- Örnek: Change the Value of Variable "ip_address" to "10.2.3.4".
Delete
- Değişkenleri Silmek için Kullanılır.
- Örnek: Delete Variable "ip_address".
CRUD İşlemlerinin Gerçekleştirebilmesi için HTTP Verbs Kullanılır.
HTTP Client, HTTP Server'a İstek Gönderdiğinde HTTP Verb, Client'in Ne Yapmak İstediğini Belirtir. Örneğin Client, Server'daki Web Sayfasına Erişmeye Çalışıyorsa GET Verb Kullanmış Demektir.
HTTP Methods / Verbs
HTTP Metotları Hakkında Daha Fazla Bilgi için Aşağıdaki Linkleri İnceleyebilirsiniz:
HTTP Request
HTTP Client (REST Client), HTTP Server'a (REST Server) İstek Gönderdiğinde HTTP Başlığı Aşağıdaki Bilgileri İçerir:
- HTTP Verb
- URI (Uniform Resource Identifier): Client'in Erişmeye Çalıştığı Kaynağı Belirtir.
Örnek
- HTTP Client, URI A'daki Verileri (Değişkenleri) Almak için GET Mesajı Gönderiyor. HTTP Server Daha Sonra Yanıt Mesajı Gönderir, Ancak Birazdan Ayrıntılara Değineceğiz.
URI Örneği:
- 3 Ana Bölüme Dikkat Edin.
- Scheme, Protokolü Belirtir.
- Authority, İsteği Gönderdiğimiz Adresi veya Host Adını Belirtir.
- Path, Erişmek İstediğimiz Kaynağı Belirtir.
Verb ve URI, HTTP Request'in Yalnızca Bir Parçasıdır. HTTP Request, Server'a Ek Bilgi Göndermek için Ek Başlıklar İçerebilir.
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers Adresindeki Listeyi Kontrol Edebilirsiniz.
- HTTP Request Örneği:
- HTTP Request Mesajındaki Örnek Bir Ek Başlık, Client'e Geri Gönderilebilecek Veri Türleri Hakkında Server'ı Bilgilendiren Accept Başlığı olabilir.
- Örnek -> Accept: application/json veya Accept: application/xml
- Standart HTTP Başlık Alanlarını Bazı Örnekler ile Birlikte https://en.wikipedia.org/wiki/List_of_HTTP_header_fields Adresinde İnceleyebilirsiniz.
HTTP Hakkında Neden Bu Kadar Bilgi Öğrendik? Bunun Nedeni REST Client, REST Server'a API Call Yaptığında Yukarıdaki gibi Bir HTTP Request Mesajı Gönderecektir. Bu Nedenle HTTP Hakkında Bazı Temel Bilgileri Öğrenmeliyiz.
HTTP Response
Client'in HTTP Request Mesajından Sonra Server'ın HTTP Response Mesajı ile Yanıt Vermesi Gerekir.
HTTP Response, Diğer Ayrıntıların Yanı Sıra İsteğin Başarılı veya Başarısız olduğunu Belirten Durum Kodu (Status Code) İçerecektir.
Durum Kodunun İlk Hanesi Yanıtın Sınıfını Gösterir:
- 1xx Informational - İstek Alındı, Süreç Devam Ediyor.
- 2xx Successful - İstek Başarıyla Alındı, Anlaşıldı ve Kabul Edildi.
- 3xx Redirection - İsteği Tamamlamak için Daha Fazla İşlem Yapılması Gerekiyor. Örneğin Kaynağın URI'si Değiştirilmişse Bu Client'e Bildirilir.
- 4xx Client Error - İstek Hatalı Sözdizimi İçeriyor veya Yerine Getirilemiyor.
- HTTP Client, URI: G'deki Verilere (Değişkenlere) Erişmek için GET Mesajı Gönderiyor. Ancak URI: G'deki Veriler HTTP Server'da Mevcut olmadığından Server, Kaynağın Bulunamadığını Belirten 404 Durum Kodu ile Yanıt Gönderir.
- 404 Durum Kodunu Muhtemelen Tanıyacaksınızdır, Daha Önce İnternette Görmüşsünüzdür.
- Örneğin google.com/networkous Adresine Erişmeye Çalıştım ve Bir Hata Mesajı Aldım. Kaynağın Bulunamadığını Belirten 404 Durum Koduna Dikkat Edin.
- 5xx Server Error - İsteğin Geçerli Olduğu, Ancak Server'ın Herhangi Bir Nedenle İsteği Yerine Getiremediği Anlamına Gelir. Örneğin Server, İsteğin HTTP Sürümünü Desteklemiyor olabilir.
Aşağıda Her Bir HTTP Response Sınıfı için Bazı Örnekler Verilmiştir:
- 1xx Informational
- 102 Processing, İsteği Alındığını ve İşlendiğini, Ancak Yanıtın Henüz Hazır Olmadığını Belirtir.
- 2xx Successful
- 200 OK, İsteğin Başarılı Olduğunu Belirtir (GET Mesajına Yanıt Olarak).
- 201 Created, İsteğin Başarılı Olduğunu ve Yeni Kaynağın Oluşturulduğunu Belirtir (POST Mesajına Yanıt Olarak).
- 3xx Redirection
- 301 Moved Permanently, İstenen Kaynağın Taşındığını Belirtir ve Server, Kaynağın Yeni Konumunu Client'e Bildirir.
- 4xx Client Error
- 403 Unauthorized, Client'in Yanıt Almak için Kimlik Doğrulama Yapması Gerektiği Anlamına Gelir.
- 404 Not Found, İstenen Kaynağın Bulunamadığını Gösterir.
- 5xx Server Error
- 500 Internal Server Error, Server'ın Başa Çıkamadığı Beklenmedik Bir Şey ile Karşılaştığı Anlamına Gelir.
HTTP Response Durum Kodları Hakkında Daha Fazla Bilgi ve Örnek için Aşağıdaki Linkleri İnceleyebilirsiniz.
REST (Representational State Transfer)
- REST, Bir API Değildir. API oluşturmak için Kullanılan Bir Çerçevedir (Framework).
- API'nin Nasıl Çalışması Gerektiğine İlişkin Bir Dizi Kural İçerir.
- REST APIs, REST-Based APIs veya RESTful APIs olarak da Bilinir.
- REST Mimarisinin Altı Kuralı Şunlardır:
- Uniform Interface
- Client-Server
- Stateless
- Cacheable or Non-Cacheable
- Layered System
- Code-on-Demand (İsteğe Bağlı)
- Daha Fazla Ayrıntı için Bu Linki İnceleyebilirsiniz: https://restfulapi.net/rest-architectural-constraints/
REST: Client-Server
- REST API'ler, Client-Server Mimarisini Kullanır.
- Client, Server'daki Kaynaklara Erişmek için API Call (HTTP Request) Kullanır. Server, HTTP Response Mesajı ile Cevap Verir. Server Yalnızca Client'den Gelen İstekleri Bekler. Server, Kaynaklarının Durumu Hakkında Client'e Kendi Başına Bilgi Göndermeye Çalışmaz.
- Client-Server Mimarisine Zaten Aşina olduğunuzu Düşünüyorum. Ağların Çoğunda Kullanılıyor.
REST: Stateless
- REST API Mesaj Değişimleri Durumsuzdur (Stateless).
- Stateless, Her Bir REST API Mesaj Değişiminin, Client ve Server Arasındaki Tüm Geçmiş Mesaj Değişimlerinden Bağımsız, Ayrı bir Olay Olduğu Anlamına Gelir.
- Server, Yeni İsteklere Nasıl Yanıt Vermesi Gerektiğini Belirlemek için Önceki İstekler ile İlgili Bilgileri Saklamaz. Her Yeni İstek Tamamen Ayrı bir Olaydır.
- Eğer Kimlik Doğrulaması Gerekiyorsa Client'in Yaptığı Her Bir İstek için Server ile Kimlik Doğrulama Yapılması Gerekir.
- TCP, Stateful Bir Protokol Örneğidir. TCP, Hostlar Arasındaki Mesaj Değişimlerini Takip Etmek için Bağlantılar Kurar ve Sequence / Acknowledgement Numaralarını Kullanır.
- UDP, Stateless Bir Protokol Örneğidir.
- REST API, Layer 4 Protokolü olarak TCP'yi Kullanan HTTP Kullansa da HTTP ve REST API'nin Kendisi Stateful Değildir. OSI Katmanlarının İşlevleri Ayrıdır. Stateful olan Bir Layer 4 Protokolünün Kullanılması, Application Katmanı Protokolünün de Stateful Olması Gerektiği Anlamına Gelmez.
REST: Cacheable or Non-Cacheable
- REST API, Verilerin Önbelleğe Alınmasını Desteklemelidir.
- Caching, Verilerin Gelecekte Kullanılmak Üzere Depolanması Anlamına Gelir.
- Örneğin Bilgisayarınız Web Sayfasının Birçok Öğesini Önbelleğe Alabilir. Böylece Web Sitesini Her Ziyaret Ettiğinizde Sayfanın Tamamını Almak Zorunda Kalmaz. Bu, Client için Performansı Artırır ve Server Üzerindeki Yükü Azaltır.
- Tüm Kaynaklar Önbelleğe Alınabilir (Cacheable) olmak Zorunda Değildir. Server, Kaynakları Client'e Gönderdiğinde Önbelleğe Alınabilir olarak Bildirmelidir. Böylece Client Kaynakları Gelecekte Kullanmak Üzere Önbelleğe Alır.
REST API'ler İletişim için HTTP Kullanmak Zorunda Değildir. Ancak HTTP En Yaygın Seçimdir ve Daha Fazla Güvenlik için HTTPS kullanılır.
REST API Özet
Cisco DevNet
Cisco Ürünleri, Platformları ve API'leri ile Uygulamalar Yazmak ve Entegrasyonlar Geliştirmek İsteyenlere Yardımcı olmak için Cisco'nun Developer Programıdır.
DevNet, Otomasyon Hakkında Bilgi Edinmek ve Becerilerinizi Geliştirmek için Kurs, Tutorial, LAB, Sandbox, Dokümantasyon gibi Birçok Ücretsiz Kaynak Sunar. Ağ Otomasyonu ile İlgileniyorsanız DevNet Sertifikasının da olduğunu Unutmayın.
Postman Programını Kullanarak DNA Center Sandbox'a REST API Call Göndereceğiz.
- DNA Center = Cisco SDN Controller. Bir Sonraki Yazıda SDN Mimarisi Hakkında Daha Derine İndiğimizde Bunu Ele Alacağız.
- DevNet, İstediğiniz Zaman Erişmekte Özgür olduğunuz Çeşitli Sandbox'lara Sahiptir. Bu Durumda DNA Center Sandbox Kullanacağız.
- Postman, API'ler Oluşturmak ve Kullanmak için Bir Platformdur.
Başlamak için:
- https://developer.cisco.com/ Adresinde Bir Hesap oluşturun.
- Ayrıca https://www.postman.com/ Adresinde Bir Hesap oluşturun ve Desktop Uygulamasını İndirin.
DevNet Üzerinde Aşağı Linkteki Öğreticiyi Takip Edeceğiz:
İlk olarak Kendinizin Denemesini Tavsiye Ederim. Yaptığım Her şeyi Takip Ediyor olsanız Bile Her Bir Adımın Nedenini Açıklayacağı için Yukarı Linkteki Öğreticiyi okuduğunuzdan Emin olun.
API Calls to DNA Center
Postman Desktop App
- Workspace
- My Workspace
Herhangi Bir Workspace Yoksa Create Workspace Butonu ile Oluşturabilirsiniz.
Ardından New Butonuna Tıklayın.
Ne Yapmak İstediğinizi Soran Bir Pencere Açılacaktır. Örneğin Yeni bir API, API için Dokümantasyon, API'leri Test Etmek için Mock Server, vb. oluşturabilirsiniz.
Bu Durumda DevNet DNA Center Server'a Göndereceğimiz HTTP Request Oluşturmak İstiyoruz.
HTTP Request Seçtikten Sonra Artık DNA Center'ın REST API'sine Ne Tür (HTTP Verbs) HTTP Request Göndermek İstediğimizi Belirtebiliriz.
DevNet Tutorial'da Açıklandığı gibi Önce HTTP Request için Kullanacağımız Authorization Token Oluşturmamız Gerekiyor.
İlk olarak HTTP Verb: POST olarak Ayarlayın, Varsayılan olarak GET Durumdadır. Ardından URL Belirtmeliyiz.
DevNet Tutorial URL Terimini Kullanıyor, Ancak Bu Yazıda URI Terimini Kullandık. Temel olarak URL, Bir URI Türüdür. Daha Fazla Bilgi için Google'da 'URI vs URL' Araması Yapabilirsiniz.
URL: https://sandboxdnac.cisco.com/api/system/v1/auth/token
Dolayısıyla Bu URL'ye POST Türünde HTTP Request Gönderirsek Authorization Token Oluşturulacaktır. Ancak Bunun olması için Username / Password Belirtmemiz Gerekiyor. Bunu Yapmak için Authorization Sekmesine Tıklayın ve Ardından Basic Auth Seçin. Kimlik Bilgilerini Girmeniz Gereken Menü Açılacaktır. Username: devnetuser, Password: Cisco123!
POST İsteğini DNA Center'ın REST API'sine Göndermek için Send Butonuna Tıklayın.
POST Başarılı olursa 200 OK Durum Kodu ile Yanıt Alırsınız.
Yanıt Mesajında Authorization Token Değerini JSON Anahtar / Değer Çifti Biçiminde Görebilirsiniz. Değeri Kopyaladığınızdan Emin olun. Yukarıdaki Resimde Sadece Vurguladığım Kısmı Kopyalamanız Yeterlidir.
Artık DNA Center Controller'dan Cihaz Envanteri Almak için İkinci API Call Göndermeye Hazırız.
İlk olarak HTTP Verb'i GET olarak Değiştirin. Bu İsteği, Tutorial'da Yazdığı gibi Farklı Bir URL'ye Göndereceğiz.
URL: https://sandboxdnac.cisco.com/api/v1/network-device
HTTP Request ile Birlikte Authentication Token Bilgisini de Göndermek için Ek Bir HTTP Başlığı Eklemeliyiz.
Bunu yapmak için Headers Sekmesine Tıklayın. Anahtar (Key) için 'X-Auth-Token' Yazın ve Önceki API Call ile DNA Center'dan Aldığımız Authorization Key'i Değer (Value) Alanına Yapıştırın.
GET Request Göndermek için Send Butonuna Tıklayın.
GET Başarılı olursa Yine 200 OK Durum Kodu ile Yanıt Alırsınız.
Yanıt Mesajında DNA Center Controller Tarafından Yönetilen Cihazların Envanterini Listeleyen JSON Formatında Veri Bulunmaktadır.
Buradaki Veri oldukça Uzun, Ancak Cihazlardan Birinin Çıktısını İnceleyelim.
Yukarı Resimdeki Çıktıya Bakarak DNA Center Controller Tarafından Yönetilen Bu Cihaz Hakkında Bilgi Edinebiliriz.
"family":"Switches and hubs" -> Hub'lar Artık Kullanılmadığından Bunun Bir Switch olduğunu Anlayabiliriz.
"role":"ACCESS" -> Access Layer Switch.
"hostname":"leaf1.abc.inc" -> leaf1 İfadesinden Bu Cihazın Data Center'da Kullanılan Spine-Leaf Mimarisindeki Leaf Switch olduğu Anlamını Çıkartabiliriz.
"platformId":"C9300-24U" -> Bu Cihazın Modeli: Catalyst 9300. C9300 Fotoğrafı:
"upTime": 29 days, 19:40:48.91" -> Cihazın Açılmasından Bu Yana Ne Kadar Zaman Geçtiğinin Bilgisini Verir.
DNA Center Controller'dan Verileri Makine tarafından Okunabilir Bir Formatta, JSON olarak Aldık. DNA Center ile Etkileşime Giren, Verileri Alan ve DNA Center'a Verileri Değiştirmesini Söyleyen Uygulamalar Yazabiliriz. Umarım API'lerin Faydasını Görmüşsünüzdür.
Ele Aldığımız Konular
Quizs
Cevaplar (Sırası ile):
- b
- c
- b
- c
- a
Okuduğunuz için Teşekkürler.
Yorum Gönder
Yorum Gönder