obenplus.com | oben+ | Hikayesi bol bir yazılımcının kaleminden, teknoloji dünyasını en önemli ve en ince ayrıntısına kadar takip etmek, bir yazılımcının hayatını, yaşantısını gözlemlemek isteneyenler için...

All posts tagged rest api

Blogumdaki yazılar, hiç bir maddi amaç güdülmeden, tamamen Türk yazılımcılarına, Türkçe kaynak olabilmesi için hazırlanmış yazılardır. Bu nedenle, yazıya verilen emeğin bir sonucu olarak, yazıyı benimle iletişime geçip iznimi almadan paylaşmamanızı rica ederim. Yazılarımın paylaşılması durumunda doğacak olan yasal haklarımı kullanabileceğimi belirtmek isterim.

Yazı içerisindeki kodlar ve örnekler, kısıtlı zaman içerisinde hazırlandığı için, bir takım hatalar içerebilmektedir. Bu konuda beni mail ya da telefon yolu ile bilgilendirebilirseniz, sevinirim.

Bu yazı içerisinde REST API kullanımı çok fazla bulunmaktadır. Bu nedenle yazıya başlamadan önce REST API konseptini bildiğinizden emin olunuz. Emin değilseniz lütfen buradaki ve buradaki yazılarımı okuyarak konuya hazırlanınız.

Elasticsearch’ü bilgisayarınıza nasıl kuracağınıza ve Elasticsearch Marvel, Sense hakkında detaylı bilgiye bu yazımdan ulaşabilirsiniz.

Amaç

ElasticSearch (Aslında ElasticSearch eski adı, artık Elastic olarak anılıyor fakat bende alışkanlık oldu, ElasticSearch olarak yazacağım), büyük ölçekli, açık kaynak kodlu bir arama motorudur. Apache Lucene üzerine kurulmuş bir yapısı vardır ve kulağa en hoş gelen özelliği sunduğu REST API sayesinde, kolaylıkla kullanılabilir olmasıdır. Bu tutorialde sizlere Elasticsearch’ün anahtar konseptlerinden bahsetmeye çalışacağım.

Sense ile Elasticsearch REST API Kullanımı

Elastic’i indirip, bir instanceına sahip olduğunuz andan itibaren, artık sizinle REST API üzerinden JSON bazlı olarak localhost’un 9200 portundan konuşan bir Elasticsearch cluster’ına sahip olmuş oluyorsunuz. Bu durumun doğal sonucu olarak, herhangi bir HTTP Client’ı kullanarak, Elastic ile konuşabilir hale geliyorsunuz. Elasticsearch’ün kendi dökümantasyonunda genelde Sense ya da CURL komutları ile örneklemeler yapılmıştır. Herneyse, eğer siz Sense ya da CURL kullanmaya istekli değilseniz, herhangi bir grafiksel HTTP client uygulamasını bilgisayarınıza indirerek kurabilirsiniz.

Daha proaktif olsun farklı bir çözüm ama kullanışlı bir çözüm arıyorum diyorsanız, size Google Chrome’un bir extensionu olan Sense pluginini önerebilirim. Plugini buradan ekleyebilirsiniz. Sense plugin sayesinde Elastic’in REST API’sine basit ve prettify edilmiş bir UI üzerinden ulaşmanız mümkün. Burada ayrıca pluginin bir özelliği olarak Autocomplete ile Elastic’in query syntaxına kolaylıkça adapte olabilirsiniz. Bir request’i run etmeniz için CTRL+Enter demeniz yeterli.

Bu tutorial boyunca, sizlere Marvel -> Sense üzerinden Curl requestleri kullanarak elastic üzerinde işlem yapma konusunda bilgi aktarımı sağlayacağım. Bu nedenle sizlere önceki yazımda anlattığım Marvel plugin’ini kurmayı şiddetle tavsiye ediyorum.

Screen Shot 2015-07-21 at 22.33.40

CRUD

İlk aşama olarak her ne kadar Elastic’i arama işlemleri için kullanmayı istesek de, ilk aşamada yapmamız gereken, bir index populate etmek ve içerisine data yerleştirmek. Elastic açısından aslında CRUD işlemi bir indexleme işlemidir ve ilk öğrenmemiz gereken şey, update, read, delete ve create işlemlerinin nasıl olduğudur.

Indexleme İşlemi Ne Demektir ?

Elasticsearch için indexleme işlemi, CRUD metninin içerisinde geçen iki harfin yani “Create” ve “Update” in karşılığıdır. Eğer bir dökümanı bir type ve document id ile indexlersek, aslında eğer böyle bir döküman yoksa ekleme yapılır, ya da aynı tip ve document id içeren bir kayıt varsa bu durumda da overwrite işlemi yapılır yani mevcut silinir, üzerine yazma işlemi yapılır.

Dilerseniz hep birlikte, ilk indexleme işlemimizi yapalım. HTTP açısından bir JSON objemizi Elastic Engine’e göndermek için POST ya da PUT request göndermemiz gerekmektedir. Eğer dökümanın ID değerini biliyorsak, bu durumda PUT, bilmiyorsak POST kullanmamız gerekiyor.

Gelin index, type, document id terimleri iyice kafamızı karıştırmadan önce bir bu terimlere değinelim.

Index

An index is like a database in a relational database. It has a mapping which defines multiple types. An index is a logical namespace which maps to one or more primary shards and can have zero or more replica shards.

Index, relational bir veritabandaki veritabanına benzer anlam taşır. İçerisinde çok sayıda type barındırabilir. Bir index aslında, bir ya da daha fazla shard’ın mantıksal namespace’i anlamına gelmektedir. Elasticsearch’e bir indexleme işlemi yapılırken, ilgili index henüz yaratılmamış ise, Elastic kendisi bu indexi otomatik olarak yaratır.

Type

A type is like a table in a relational database. Each type has a list of fields that can be specified for documents of that type. The mapping defines how each field in the document is analyzed.

Type aslında, ilişkisel bir veritabanındaki tablolara benzemektedir. Her bir type içerisinde field listesi barındırır ve ilgili type’a özeldir. Elasticsearch indexleme sürecindeki mapping süreci aslında, type içerisindeki field’lerin nasıl analiz edildiği ile ilgilidir.

Document

A document is a JSON document which is stored in elasticsearch. It is like a row in a table in a relational database. Each document is stored in an index and has a type and an id. A document is a JSON object (also known in other languages as a hash / hashmap / associative array) which contains zero or more fields, or key-value pairs. The original JSON document that is indexed will be stored in the _source field, which is returned by default when getting or searching for a document.

Document aslında bir JSON metninin Elastic’de tutulan haline deniyor. Nasıl index database i , type o database in içerisindeki bir tabloyu ve field o tablonun sütunlarını ifade ediyorsa, document’de tablodaki bir satırı ifade ediyor. Her bir döküman aslında index + type + id den oluşan bir bilgi anlamına geliyor. Elastic ile aklınıza gelen tüm JSON metinlerini indexlemeniz mümkündür.

Field

A document contains a list of fields, or key-value pairs. The value can be a simple (scalar) value (eg a string, integer, date), or a nested structure like an array or an object. A field is similar to a column in a table in a relational database. The mapping for each field has a field type (not to be confused with document type) which indicates the type of data that can be stored in that field, eg integer, string, object. The mapping also allows you to define (amongst other things) how the value for a field should be analyzed.

Bir döküman, aslında bir tablodaki bir satırı ifade eder dediğimize göre, bu tablodaki sütunları ifade eden döküman, aslında field listesinden meydana gelmektedir. Herhangi bir field’a gelen değer, bir simple data da olabilir (integer, long, date, string vb. ) , kompleks bir tip de olabilir (array ya da obje vb.). Yani field, bir tablodaki sütunlar anlamına gelmektedir. Field’lar map edilirken, her bir field’in tipi, Elastic tarafından otomatik olarak algılanır.

İlk Index

Terimlerin anlamlarını da kavradığımıza göre, pratik kazanmak için ilk request’imizi gönderelim.

Bu request içerisinde library -> index , books -> type ve 1 -> document id anlamına gelmektedir. İlgili dökümanın fieldları, title, name.first, name.last, publish_date ve price ‘dır.

Bu çağrıyı Elastic’e yaptığımız anda aşağıdaki yanıtı alırız;

Read more


Merhaba arkadaşlar,

Uzun zamandır teknik bir yazı paylaşmamıştım, bu sene daha sık paylaşımda bulunmayı düşünüyorum. Günümüzün popüler konularından birisiyle 2015 yılının ilk yazısına başlıyorum. Konumuz REST Api nedir ?

Bu yazıyı REST sözcüğünü ilginç bulup okuyanlar için önce API nedir den başlayalım 🙂 Api, Application Programming Interface kelimelerinin baş harflerinden oluşan bir kısaltmadırapi Bir uygulamanın bir takım fonksiyonlarının başka uygulamalar tarafından kullanılmasına olanak sağladığı yapıya API diyoruz özetle.

Günümüzde iki sistemin haberleşmesinde kullanılan trend olmuş iki tip servis haberleşmesi var. Bir tanesi SOAP ve diğeri de REST. Ben çok kısa, SOAP dan da bahsedeceğim, REST ile arasındaki farkları anlamak açısından.

SOAP dediğimiz arkadaşımızın Simple Object Access Protocol – Basit Nesne Erişim Protokolü isminde uzunca bir ismi var. SOAP web servis çağrılarında Remote Procedure Call (RPC) modelini kullanan, istemci/sunucu mantığına dayalı bir protokoldür. Daha da özet hali, bir servis var ve bunun metodları var, siz de bu metodları call ederek response alıyorsunuz. SOAP da request / response süreci tümüyle XML olarak iletilmektedir.

Örnek SOAP servis;

axqSol tarafta iki örnek SOAP servis metodu görüyorsunuz. Bir tanesi getLastVersion, diğeri de getSozlesme metodu. Mantık ise oldukça basit, getLastVersion metodunu hiç bir input vermeyerek çağırdığınızda, uygulama size bir element dönüyor, bu element in tipi string ve unique bir değer.

SOAP servisleri denemek istiyorsanız, SOAP UI isimli toolu şiddetle öneririm. Oldukça kullanışlı olan bu tool ile servisimizi deneyecek olursak;

 

 

Request;

Response;

Şeklinde olmaktadır. Görüldüğü üzere bütün veriler XML olarak gidip gelmektedir. Bu da SOAP ın artık old-fashioned olması için geçerli bir sebep aslında.

Gördüğünüz gibi psikolojik olarak SOAP ın insanda verdiği hissiyat, bir sürü text ama anlaşılır bir yapı gibi. Eğer siz de öyle düşünüyorsanız, REST i korkmadan algılamaya çalışırsanız, ön yargılarınızı yıkarsanız, daha simple birşey olduğunu anlayacaksınız.

REST (Representational state transfer) Nedir ?

  1. REST client-server iletişimiyle ilgili bir mimari.
  2. SOAP, RPC gibi kompleks mimarilerle sağlamak yerine, HTTP protokolü üzerinden saglamak.
  3. SOAP, RPC’nin aksine basit ve hafiftirler.
  4. Esnek olup, SOAP gibi keskin standartları yoktur.
  5. SOAP ile en büyük farkı, SOAP gibi bizi proxy kullanmaya, bir WSDL’e zorlamıyor olması.
  6. Entegre etmesi kolay.

Yukarıdaki maddelerin üzerinden tek tek geçmekte fayda var. İlk maddemiz ve ikinci maddemizi ortak düşünelim. Ortada bir client, bir server var, bu client aslında sadece POST, GET, PUT, DELETE vb. gibi bir kaç kelimeyi biliyor ve HTTP üzerinden haberleşme yapılıyor. Ne kadar simple olduğunu gelin siz düşünün 🙂

Standartı yoktur REST’in. Yani kafanıza estiği gibi bir mapping mimarisi uydurabilirsiniz. (Tabi saçma olmaması lazım) Özetle method call gibi değil, adeta bir ağaç mantığıyla api call yapabiliyorsunuz.

PROXY yok, WSDL yok, XML ile uğraşmak yok. Request yap html üzerinden, al responsu JSON üzerinden, bu kadar basit 🙂

REST Request Tipleri:
  • GET : Belirtilen collection’ın URI’lerini veya detaylarını listelemede kullanılır.
  • PUT: Bütün bir collection’ı başka bir collection’la yer değiştirmek için kullanılır.
  • POST: Yeni bir collection oluşturmak için kullanılır ve yeni oluşturulan collection’ın URI’si döndürülür.
  • DELETE: Tüm Collection’ı silmek için kullanılır.
REST Apilerde Dönülen HTTP Status Kodları (Yaygın Kullanılanlar)

200 OK: Genelde veri listeleme sonuçları 200 ile dönüş yapılır.
201 CREATED: Veri eklendiği zaman verinin kendisi ile 201 dönülüyor.
204 NO CONTENT: Veri silindiği zaman 204 dönülüyor.
400 BAD REQUEST: Genel olarak kayıt ekleme ya da güncelleme isteklerinde gönderilen veri validasyondan geçemediyse neden geçemediği hakkında bilgiyle beraber 400 http statusuyla dönülür.
403 Forbidden: Yetkiye dayalı bir işlem yapılıyorsa bu api uç noktasında işlem yapmaya çalışan kişinin bu işlemi yapmaya yetkisi yoksa 403 status kodu döndürülür.
401 Unauthorized: Api ucunuzda bu işlemi yapmak için login olmak zorunlu ise ve apiye istek yapan kullanıcı login değil ise bu http status ile cevap verilir. Örneğin kullanıcının kendi bilgilerinin güncellemesi denilebilir.
404 Not Found: Bu http status  kullanıcının istek yaptığı url yok ise ya da url deki veri geçersiz ise bu hatayı alırız. örneğin şöyle bir url miz olsun /api/v1/account/bahattincinic sondaki bölüm kullanıcı adı. Buraya sistemimizde olmayan bir kullanıcı girersek 404 alırız.
405 Method Not Allowed:
Bu http status u istek yapılan api uç noktası gönderilen methodu implemente etmemiş ise bu http status unu alırız. Örneğin login olması için token verdiğimiz bir api ucumuz var ve bu uçta sadece post isteğini kabul ediyor. Kullanıcı bu api urline GET isteği yaparsa bu hatayı alır.

429 Too Many Requests: Bu http statusunu saatlik ya da dakikaklık kısıtlanan sınırdan fazla istek yaparsak bu http statusunu alırız. 
Read more