Node.js REST API'leri Yazmanın En İyi 10 Uygulaması

Bu makalede, Node.js REST API'lerini yazmak için, rotalarınızı adlandırma, kimlik doğrulama, kara kutu testi ve bu kaynaklar için uygun önbellek başlıklarını kullanma gibi konular dahil olmak üzere en iyi uygulamaları ele alıyoruz.

Node.js için en popüler kullanım örneklerinden biri, RESTful API'lerini kullanarak yazmaktır. Yine de müşterilerimizin Trace ile uygulamalarındaki sorunları bulmalarına yardımcı olurken, Node.js izleme aracımız, geliştiricilerin REST API'leri ile ilgili birçok sorun yaşadıklarını sürekli olarak tecrübe ediyoruz.

Umarım RisingStack'ta kullandığımız bu en iyi uygulamaların yardımcı olabileceğini umuyorum:

# 1: HTTP Yöntemlerini ve API Yollarını Kullan

Kullanıcıları oluşturmak, güncellemek, almak veya silmek için bir Node.js RESTful API oluşturduğunuzu hayal edin. Bu işlemler için HTTP zaten yeterli araç setine sahip: POST, PUT, GET, PATCH veya DELETE.

En iyi uygulama olarak, API rotalarınız her zaman isimleri kaynak tanımlayıcı olarak kullanmalıdır. Kullanıcının kaynaklarını konuşurken, yönlendirme şunun gibi görünebilir:

  • POST / kullanıcı veya PUT / kullanıcı: / id, yeni bir kullanıcı oluşturmak için
  • Kullanıcı listesini almak için AL / kullanıcı,
  • Bir kullanıcı almak için GET / user /: kimliği,
  • PATCH / user /: mevcut bir kullanıcı kaydını değiştirmek için kimliği,
  • DELETE / user /: bir kullanıcıyı kaldırmak için id.

# 2: HTTP Durum Kodlarını Doğru Kullanın

Bir istek sunarken bir şeyler ters giderse, cevapta bunun için doğru durum kodunu ayarlamanız gerekir:

  • 2xx, eğer her şey yolundaysa,
  • 3xx, kaynak taşınmışsa,
  • 4xx, müşteri hatası nedeniyle istek yerine getirilemezse (mevcut olmayan bir kaynak istemek gibi),
  • 5xx, API tarafında bir şeyler ters giderse (bir istisna olduğu gibi).

Express kullanıyorsanız, durum kodunu ayarlamak res.status (500) .send ({error: 'Dahili sunucu hatası oldu'}) kadar kolaydır. Restify ile benzer şekilde: res.status (201).

Tam liste için, HTTP durum kodlarının listesini kontrol edin.

# 3: Meta Veri Göndermek için HTTP başlıklarını kullanın

Göndermek üzere olduğunuz yüke ilişkin meta veri eklemek için HTTP başlıklarını kullanın. Bu gibi başlıklar hakkında bilgi olabilir:

  • sayfalama,
  • oranı sınırlayıcı,
  • veya kimlik doğrulaması.

Standartlaştırılmış HTTP başlıklarının bir listesi burada bulunabilir.

Üstbilgilerinizde herhangi bir özel meta veri ayarlamanız gerekiyorsa, bunları X ile öneklemek en iyi yöntemdi. Örneğin, CSRF belirteçleri kullanıyorsanız, bunları X-Csrf olarak adlandırmanın genel (standart dışı) bir yoluydu. -Jeton. Bununla birlikte RFC 6648 ile kullanımdan kaldırıldılar. Yeni API'ler, diğer uygulamalarla çakışabilecek başlık adlarını kullanmamak için ellerinden geleni yapmalıdır. Örneğin, OpenStack başlıklarını OpenStack ile ön ekler:

Openstack-Kimlik-Hesap Kimliği
Openstack-Ağ-Sunucu-Adı
Openstack-Nesne-Depolama-Politika

HTTP standardının başlıklarda herhangi bir boyut sınırı tanımlamadığını unutmayın; bununla birlikte, Node.js (bu makalenin yazılmasından itibaren), pratik nedenlerle, üstbilgi nesnesine 80KB boyut sınırı uygular.

“HTTP başlıklarının (durum satırı dahil) toplam boyutunun HTTP_MAX_HEADER_SIZE değerini geçmesine izin verme. Bu kontrol, saldırganların bize saldırganın arabelleğe almayı sürdürdüğü hiç bitmeyen bir başlık beslediği hizmet reddi saldırılarına karşı korumak için burada. "
Node.js HTTP ayrıştırıcısından

# 4: Node.js REST API'niz için doğru çerçeveyi seçin

Kullanım durumunuza en uygun çerçeveyi seçmek önemlidir.

Express, Koa veya Hapi

Express, Koa ve Hapi, tarayıcı uygulamaları oluşturmak için kullanılabilir ve bu nedenle, yalnızca birkaç özelliği isimlendirmek için şablon oluşturmayı ve görüntülemeyi destekler. Uygulamanızın kullanıcıya dönük tarafı da sağlaması gerekiyorsa, onlar için de geçerli olur.

Restify

Öte yandan, Restify, REST hizmetleri oluşturmanıza yardım etmeye odaklanıyor. Sürdürülebilir ve gözlenebilir "katı" API hizmetleri oluşturmanıza izin vermek için vardır. Restify ayrıca tüm işleyicileriniz için otomatik DTrace desteği ile birlikte gelir.

Restify, npm veya Netflix gibi büyük uygulamalarda üretimde kullanılır.

# 5: Black-Box Node.js REST API'lerinizi sınayın

REST API'lerinizi test etmenin en iyi yollarından biri, onlara kara kutu olarak davranmaktır.

Kara kutu testi, bir uygulamanın işlevselliğinin iç yapıları veya çalışmaları hakkında bilgisi olmadan incelendiği bir test yöntemidir. Dolayısıyla, bağımlılıkların hiçbiri alay etmiyor ya da engellenmiyor, ancak sistem bir bütün olarak test ediliyor.

Size kara kutu sınaması konusunda yardımcı olabilecek modüllerden biri Node.js REST API'leri üstündür.

Bir kullanıcının test çalıştırıcısı mocha kullanılarak döndürülüp döndürülmediğini kontrol eden basit bir test durumu şöyle uygulanabilir:

const request = zorunlu ('süper')
 
tarif et ('GET / user /: id', function () {
  it ('bir kullanıcı döndürür', function () {
    // yeni mocha sürümleri aynı zamanda taahhütleri de kabul eder
    iade isteği (uygulama)
      .get ( '/ kullanıcı)
      .set ('Kabul et', 'uygulama / json')
      İnceleme (200, {
        id: '1'
        İsim: 'John Math'
      }, tamamlandı)
  })
})

Sorabilirsiniz: Veriler REST API'sini sunan veritabanına nasıl yerleştirilir?

Genel olarak, testlerinizi, sistemin durumu hakkında mümkün olduğunca az varsayım yapacak şekilde yazmak iyi bir yaklaşımdır. Yine de, bazı senaryolarda, sistemin tam olarak ne olduğunu bilmeniz gerektiğinde kendinizi bir noktada bulabilirsiniz, böylece iddialarda bulunabilir ve daha yüksek test kapsamı elde edebilirsiniz.

Böylece, gereksinimlerinize bağlı olarak, veritabanını test verileriyle aşağıdaki yöntemlerden biriyle doldurabilirsiniz:

  • Kara kutu sınama senaryolarınızı, bilinen bir üretim verisi alt kümesinde yayınlayın,
  • Test durumları çalıştırılmadan önce veritabanını hazırlanmış verilerle doldurun.

Elbette, kara kutu testi, birim testi yapmak zorunda olmadığınız anlamına gelmez, yine de API'leriniz için birim testi yazmanız gerekir.

# 6: JWT Tabanlı, Vatansız Kimlik Doğrulama mı

REST API’lerinizin durumsuz olması gerektiğinden, kimlik doğrulama katmanınız da öyle. Bunun için JWT (JSON Web Token) idealdir.

JWT üç bölümden oluşur:

  • Belirteç türünü ve karma algoritmayı içeren başlık
  • Talepleri içeren taşıma yükü
  • İmza (JWT yükü şifrelemez, imzalar!)

JWT tabanlı kimlik doğrulamasını uygulamanıza eklemek çok basittir:

const koa = zorunlu ('koa')
const jwt = zorunlu ('koa-jwt')
const app = koa ()
app.use (jwt ({
  sırrı: 'çok sır'
}))
// Korumalı katman yazılımı
app.use (function * () {
  // belirtecin içeriği this.state.user'de mevcut olacak
  this.body = {
    sırrı: '42'
  }
})

Bundan sonra, API uç noktaları JWT ile korunur. Korunan bitiş noktalarına erişmek için, Yetkilendirme başlığı alanında belirteci sağlamanız gerekir.

kıvırmak - başlık "Yetki: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwI
iwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30
RMHrHDcEfxjoYZgeFONFh7HgQ "my-website.com

Fark edebileceğiniz bir şey, JWT modülünün herhangi bir veritabanı katmanına bağlı olmadığıdır. Bu, tüm JWT belirteçlerinin kendi başlarına doğrulanabildiği ve ayrıca canlı değerleri için zaman içerebileceği için geçerlidir.

Ayrıca, tüm API uç noktalarınıza yalnızca HTTPS kullanarak güvenli bir bağlantı üzerinden erişilebildiğinden emin olmanız gerekir.

Önceki bir yazıda, web kimlik doğrulama yöntemlerini ayrıntılı olarak açıkladık - kontrol etmenizi öneririm!

# 7: Koşullu İstekleri Kullan

Koşullu istekler, belirli HTTP başlıklarına bağlı olarak farklı şekilde yürütülen HTTP istekleridir. Bu başlıkları önkoşul olarak düşünebilirsiniz: eğer karşılanırlarsa, istekler farklı şekilde yürütülür.

Bu başlıklar, sunucuda depolanan bir kaynağın sürümünün aynı kaynağın belirli bir sürümüyle eşleşip eşleşmediğini kontrol etmeye çalışır. Bu nedenle, bu başlıklar şöyle olabilir:

  • Son değişikliğin zaman damgası,
  • veya her sürüm için farklı olan bir varlık etiketi.

Bu başlıklar:

  • Son Değiştirme Tarihi (kaynağın en son ne zaman değiştirildiğini belirtmek için),
  • Etag (varlık etiketini belirtmek için),
  • If-Modified-Since (Son Değiştirme Başlığı ile birlikte kullanılır),
  • If-None-Match (Etag başlığında kullanılır),

Bir örneğe bakalım!

Aşağıdaki müşteri, doküman kaynağının önceki sürümlerine sahip değildi, bu nedenle ne If-Modified-Since, ne de If-Match-Match başlığı kaynak gönderildiğinde uygulanmadı. Ardından, sunucu Etag ve Son Değiştirme Tarihi başlıklarının gerektiği gibi ayarlanmasıyla yanıt verir.

MDN Koşullu istek dokümantasyonundan

İstemci If-Modified-Since ve If-None-Match başlıklarını aynı kaynağı talep etmeye çalıştığında başlatabilir - çünkü şimdi bir sürümü vardır. Yanıt aynı olursa, sunucu yalnızca 304 - Değişiklik yapılmadı durumuyla yanıt verir ve kaynağı bir daha göndermez.

MDN Koşullu istek dokümantasyonundan

# 8: Hız Sınırlamasını Kabul Et

Oran sınırlaması, belirli bir tüketicinin API'ye ne kadar istek gönderebileceğini kontrol etmek için kullanılır.

API kullanıcılarınıza kaç istek bıraktıklarını bildirmek için aşağıdaki başlıkları ayarlayın:

  • X-Rate-Limit-Limit, belirli bir zaman aralığında izin verilen istek sayısı
  • Kalan X-Rate-Limit, aynı aralıkta kalan istek sayısını,
  • X Hızı Limiti-Sıfırlama, hız limitinin sıfırlanacağı saat.

Çoğu HTTP çerçevesi, onu kutudan (veya eklentilerle birlikte) destekler. Örneğin, Koa kullanıyorsanız, koa-ratelimit paketi var.

Zaman penceresinin farklı API sağlayıcılarına göre değişebileceğini unutmayın; örneğin, GitHub bunun için bir saat kullanırken Twitter 15 dakika sürer.

# 9: Uygun bir API belgesi oluşturun

API'leri başkalarının kullanabilmesi, onlardan yararlanabilmesi için yazarsınız. Node.js için API dokümantasyonu sağlamak REST API'leri çok önemlidir.

Aşağıdaki açık kaynaklı projeler API'leriniz için dokümantasyon oluşturmanıza yardımcı olabilir:

  • API Blueprint
  • Çalım

Alternatif olarak, barındırılan bir ürün kullanmak istiyorsanız, arı kovanı için gidebilirsiniz.

# 10: API’lerin Geleceğini Kaçırmayın

Geçtiğimiz yıllarda, API'ler için iki ana sorgu dili ortaya çıktı - yani Facebook'tan GraphQL ve Netflix'ten Falcor. Ama neden onlara ihtiyacımız var?

Aşağıdaki RESTful kaynak isteğini hayal edin:

/ Org / 1 / alan / 2 / docs / 1 / işbirlikçileri?
= Email & page = 1 & limiti dahil = 10

Bu, elinizden kolayca kurtulabilir - her zaman tüm modelleriniz için aynı yanıt biçimini almak istediğiniz gibi. GraphQL ve Falcor'un yardım edebileceği yer burasıdır.

GraphQL hakkında

GraphQL, API'ler için bir sorgu dili ve bu sorguları mevcut verilerinizle yerine getirmek için kullanılan bir çalışma zamanıdır. GraphQL, API'nızdaki verilerin eksiksiz ve anlaşılır bir tanımını sunar, müşterilere tam olarak neye ihtiyaçları olduğunu ve başka hiçbir şey sormalarını sağlar, zaman içinde API'leri geliştirmeyi kolaylaştırır ve güçlü geliştirici araçlarını etkinleştirir. - Buradan daha fazla oku.

Falcor hakkında

Falcor, Netflix kullanıcı arayüzlerine güç sağlayan yenilikçi veri platformudur. Falcor, tüm arka uç verilerinizi Düğüm sunucunuzdaki tek bir Sanal JSON nesnesi olarak modellemenizi sağlar. İstemcide, get, set ve call gibi bilinen JavaScript işlemlerini kullanarak uzak JSON nesnenizle birlikte çalışırsınız. Verilerinizi biliyorsanız, API'nizi de bilirsiniz. - Buradan daha fazla oku.

İlham için İnanılmaz REST API'leri

Bir Node.js REST API'si geliştirmeye başlamak üzereyseniz veya daha eski bir sürümün yeni bir versiyonunu oluşturuyorsanız, kontrol etmeye değer dört gerçek yaşam örneği topladık:

  • GitHub API
  • Twilio API
  • Şerit API
  • DigitalOcean API

Umarım şimdi Node.js. Bir şey kaçırırsanız lütfen bana yorumlarda bildirin!

Orijinal olarak 21 Şubat 2017 tarihinde blog.risingstack.com sitesinde yayınlandı.