Node.js REST API

Paylaş

Node.js ile REST tabanlı web servis hazırlarken dikkat edilmesi gerekenler ve hazırladıktan sonra yapılması gerekenlerle ilgili bilgiler yer alıyor.

REST nedir?

REST ile ilgili detaylı bilgi için REST Nedir? yazıma bakmalısın.

REST tabanlı web servis hazırlarken herhangi bir sınırlama veya kural yoktur.

Ancak sıklıkla kullanılan ve kalıplaşmış(best practices) yapıların kullanımı iyi bir REST API için faydalı olacaktır.

1.Planlama

REST tabanlı bir web servis hazırlarken ilk olarak API içinde yer alacak işlevlerin belirlenmesi faydalı olacaktır.

Bu adımda REST API hangi amaçla kullanılacak, hangi işlevlere sahip olacak gibi web servis kapsamı belirlenir.

2.Dosya ve dizin yapısı

API ile ilgili kapsam belirlendikten sonra iyi bir dosya ve dizin yapısının oluşturulması geliştirme ve tekrar kullanılabilirlik için faydalı olacaktır.

Gelen isteklerin yönetimi ve sunumu sırasında içinde faydalı fonksiyonlar olmasından dolayı express, koa ve hapi gibi modüllerin kullanılabilir.

Dosya ve dizin yapısını kendimiz oluşturabileceğimiz gibi express generator gibi araçlarla hızlı bir şekilde oluşturabiliriz.

npm install express-generator -g

Kurulum sonrası aşağıdaki komut ile dosya ve dizin yapısı oluşturulabilir.

express API

Örneğin; JSON veya JSONP biçiminde çıktı vermek için express içinde yer alan json veya jsonp metodu kullanılabilir.

router.get('/', function (req, res, next) {
  res.status(200).jsonp({
    data: 'Merhaba dünya'
  });
});

3.Ayarların yapılması

Node.js ile REST API hazırlarken modül ayarlarının iyi hazırlanması oluşabilecek sorunları önlemek ve tekrar kullanılabilirlik için faydalı olacaktır.

Express ile hazırlanan REST API içinde JSONP kullanıldığında varsayılan olarak callback parametresine bakar.

Bu parametre express içinde yer alan set metodu ile değiştirilebilir.

app.set('jsonp callback name', 'fonksiyon');

Başka bir adresten bir istek geldiğinde güncel tarayıcılar bunu CORS olarak adlandırılan kural gereği engelleyecektir.

CORS yapısına izin vermek için express için hazırlanmış middleware kullanılabileceği gibi aşağıdaki kodlarda kullanılabilir.

app.use(function(req, res, next) {
  res.header("Access-Control-Allow-Origin", "*");
  res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
  next();
});

Dosya ve dizin yapısı ile ayarlar iyi hazırlanırsa bu yapı daha sonra başka bir web servis hazırlarken de kullanılabilir.

4.Adlandırma

Daha anlaşılır bir REST API yapısı için adlandırma olarak çoğul adların kullanımı faydalı olacaktır.

// İyi
/api/musteriler:     Tüm müşterileri getir.
/api/musteriler/25:  Sıra numarası 25 olan müşteriyi getir.

// Kötü
/api/musteri:     Tüm müşterileri getir.
/api/musteri/25:  Sıra numarası 25 olan müşteriyi getir.

// Kötü - işlem ile ilgili bilgi veriyor.
/api/musterilerigetir
/api/musterilerigetir/25

NOT: Adlandırma sırasında işlem ile ilgili bilgi vermek(musterilerigetir, musterisil, musteriguncelle) hazırlanan web servisin karmaşık olmasına neden olacaktır.

5.HTTP yöntemleri

Adlandırma sırasında işlem ile ilgili bilgi vermek yerine HTTP protokolünde yer alan HTTP yöntemleri kullanılır.

Aşağıdaki HTTP yöntemleri yaygın olarak REST tabanlı mimaride kullanılır.

GET – Veri almak için kullanılır.
PUT – Veri üzerinde değişiklik yapmak için kullanılır.
DELETE – Veri silmek için kullanılır.
POST – Veri göndermek/eklemek için kullanılır.

HTTP yöntemlerinin kullanımı hazırlanan web servis yapısını daha anlaşılır kılacaktır.

// İyi
GET    /api/musteriler
POST   /api/musteriler
PUT    /api/musteriler/:id
DELETE /api/musteriler/:id

// Kötü - Her bir işlem için ayrı tanımlama yapılmış.
/api/musterilerigetir
/api/musterilerigetir/:id
/api/musteriguncelle/:id
/api/musterisil/:id

6.HTTP durum kodları

İşlem sonucu ile ilgili bilgi vermek için HTTP protokolünde yer alan HTTP durum kodları kullanılır.

Aşağıdaki HTTP durum kodları yaygın olarak REST tabanlı mimaride kullanılır.

200 OK – İşlem başarıyla gerçekleşirse kullanılır.
201 CREATED – İşlemi başarıyla gerçekleşirse kullanılır. Eklenen veri döndürülür.
204 NO CONTENT – İşlemi başarıyla gerçekleşirse kullanılır. Eklenen, silinen veri döndürülmez.
400 BAD REQUEST – Hatalı istek veya yetkilendirme hatası için kullanılır.
401 UNAUTHORIZED – Yetkilendirme hatası için kullanılır.
403 FORBIDDEN – Yetkilendirme ve erişim hatası için kullanılır.
404 NOT FOUND – İstenilen işlem yoksa kullanılır.
405 METHOD NOT ALLOWED – İzin verilmeyen HTTP yöntemi kullanıldığında bilgi vermek için kullanılır.
409 CONFLICT – Aynı veri üzerinde birden fazla kişinin işlem yaptığını bildirmek için kullanılır.
500 INTERNAL SERVER ERROR – Sunucuda herhangi bir hata olduğunda kullanılır.

Her istek sonucunda 200 durum kodunu göndermek yerine işlem sonucuna göre ilgili işlem kodunu kullanmak faydalı olacaktır.

7.API sürümü

Geliştirilen REST API başka kullanıcı ve firma(lar) tarafından kullanılacaksa API sürümü kullanmak faydalı olacaktır.

/api/v1/musteriler/:id

REST API’de yapılan kapsamlı değişiklik sonrası sadece API sürümünün değiştirilmesi yeterli olacaktır.

/api/v1/musteriler/:id

API sürümünün verilmesi dokümantasyon ve iyi bir REST API yapısı için gereklidir.

8.Sorgu kullanımı

Geliştirilen API içinde yer alan verileri alırken çeşitli sorgu parametrelerin kullanımı esneklik ve trafik açısından faydalı olacaktır.

// Tüm müşterileri getir.
/api/v1/musteriler

// Tüm müşterileri name alanına göre sıralanmış olarak getir.
/api/v1/musteriler?sort=name&direction=asc

// Müşteriler alanında name alan değeri Yusuf olan müşterileri getir.
/api/v1/musteriler?name=Yusuf

// İlk 30 müşteriyi name alanına göre sıralanmış olarak getir.
/api/v1/musteriler?sort=name&direction=asc&limit=30

// Sıralanan müşterilerden 30 ila 60 arasındakileri getir.
/api/v1/musteriler?sort=name&direction=asc&limit=30&offset=30

Sorgu kullanımı sırasında varsayılan değer vermek gereksiz trafik kullanımını önleyecektir.

Örneğin; 10 bin müşteri kaydı varsa hepsini vermek yerine 100 tane kayıt vermek ve diğer kayıtlara limit, offset veya sayfa numarası gibi sorgu parametreleriyle erişmek faydalı olacaktır.

Ayrıca daha fazla ve daha gelişmiş sorgulama için GraphQL gibi tekniklerde kullanılabilir.

9.Test

REST API geliştirirken ve geliştirdikten sonra performans, hata ve sorunlara karşı test edilmesi faydalı olacaktır.

Test işlemi için tarayıcı veya işletim sisteminde yer alan komutlar kullanılabileceği gibi Postman, Insomnia, Paw ve SOAPUI gibi araçlarda kullanılabilir.

10.Dokümantasyon

REST tabanlı web servisler için WSDL gibi bir tanımlama ve açıklama standardı olmadığından dolayı geliştirilen REST API kara kutu olacaktır.

Geliştirilen REST API web servisinin anlaşılabilir olması için apiDoc, Swagger, API Blueprint gibi araçlar kullanılarak kullanım dokümanının hazırlanması faydalı olacaktır.

Node.js Derslerine buradan ulaşabilirsiniz…

Web Servis Derslerine buradan ulaşabilirsiniz…

Hayırlı günler dilerim.

Facebook