API proxy'si tasarımı ve geliştirme ile ilgili en iyi uygulamalar

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Bu belgenin amacı, Apigee Edge ile geliştirme yaparken kullanılabilecek bir dizi standart ve en iyi uygulama sunmaktır. Burada ele alınan konular arasında tasarım, kodlama, politika kullanımı, izleme ve hata ayıklama yer alır. Bu bilgiler, başarılı API programları uygulamak için Apigee ile çalışan geliştiricilerin deneyimlerinden elde edilmiştir. Bu dinamik bir belge olduğu için zaman zaman güncellenecektir.

Buradaki kurallara ek olarak, Apigee Edge Antipatterns topluluk gönderisini de faydalı bulabilirsiniz.

Geliştirme standartları

Yorumlar ve Belgeler

  • ProxyEndpoint ve TargetEndpoint yapılandırmalarında satır içi yorumlar ekleyin. Yorumlar, özellikle politika dosyası adları akışın temel işlevini ifade edecek kadar açıklayıcı olmadığında akışın okunabilirliğini artırır.
  • Yorumları faydalı hale getirin. Bariz yorumlardan kaçının.
  • Tutarlı girinti, boşluk ve dikey hizalama vb. kullanın.

Çerçeve tarzı kodlama

Çerçeve tarzı kodlama, API proxy kaynaklarını yerel geliştirme ortamlarında yeniden kullanmak üzere kendi sürüm denetim sisteminizde saklamayı içerir. Örneğin, bir politikayı yeniden kullanmak için kaynak kontrolünde saklayın. Böylece geliştiriciler politikayı senkronize edip kendi proxy geliştirme ortamlarında kullanabilir.

  • Mümkün olduğunda DRY ("kendini tekrar etme") ilkesini etkinleştirmek için politika yapılandırmaları ve komut dosyaları, özel ve yeniden kullanılabilir işlevler uygulamalıdır. Örneğin, istek iletilerinden sorgu parametrelerini ayıklamaya yönelik özel bir politika ExtractVariables.ExtractRequestParameters olarak adlandırılabilir. CORS başlıklarını yerleştirmek için özel bir politika AssignMessage.SetCORSHeaders olarak adlandırılabilir. Bu politikalar daha sonra kaynak kontrol sisteminizde depolanabilir ve parametreleri ayıklaması veya CORS başlıklarını ayarlaması gereken her API proxy'sine eklenebilir. Bu sayede, gereksiz (ve dolayısıyla daha az yönetilebilir) yapılandırmalar oluşturmanız gerekmez.
  • API proxy'lerinden kullanılmayan politikaları ve kaynakları (JavaScript, Java, XSLT vb.) temizleyin. Özellikle içe aktarma ve dağıtım işlemlerini yavaşlatma potansiyeli olan büyük kaynakları temizleyin.

Adlandırma Kuralları

  • Politika name özelliği ve XML politika dosya adı aynı olmalıdır.
  • Script ve ServiceCallout politikası name özelliği ile kaynak dosyasının adı aynı olmalıdır.
  • DisplayName, bu API proxy'siyle daha önce hiç çalışmamış birine politikanın işlevini doğru bir şekilde açıklamalıdır.
  • Politikaları işlevlerine göre adlandırın. Apigee, politikalarınız için tutarlı bir adlandırma kuralı oluşturmanızı önerir. Örneğin, kısa ön ekler kullanın ve ardından tirelerle ayrılmış açıklayıcı kelimeler dizisi ekleyin. Örneğin, AssignMessage politikaları için AM-xxx. apigeelint aracını da inceleyin.
  • Kaynak dosyaları için uygun uzantıları kullanın. JavaScript için .js, Python için .py ve Java JAR dosyaları için .jar uzantısını kullanın.
  • Değişken adları tutarlı olmalıdır. camelCase veya under_score gibi bir stil seçerseniz API proxy'si boyunca bu stili kullanın.
  • Değişkenleri amaçlarına göre düzenlemek için mümkün olduğunda değişken öneklerini kullanın. Örneğin, Consumer.username ve Consumer.password.

API proxy geliştirme

İlk Tasarımda Dikkat Edilmesi Gerekenler

  • RESTful API tasarımıyla ilgili rehberlik için Web API Tasarımı: Eksik Bağlantı adlı e-kitabı indirin.
  • API proxy'leri oluşturmak için mümkün olduğunda Apigee Edge politikalarından ve işlevlerinden yararlanın. Tüm proxy mantığını JavaScript, Java veya Python kaynaklarında kodlamaktan kaçının.
  • Akışları düzenli bir şekilde oluşturun. Her biri tek bir koşul içeren birden fazla akış, aynı PreFlow ve Postflow'a birden fazla koşullu ekten daha iyidir.
  • "Güvenli mod" olarak, ProxyEndpoint BasePath'i / olan bir varsayılan API proxy'si oluşturun. Bu, temel API isteklerini bir geliştirici sitesine yönlendirmek, özel bir yanıt döndürmek veya varsayılan messaging.adaptors.http.flow.ApplicationNotFound döndürmekten daha yararlı başka bir işlem gerçekleştirmek için kullanılabilir.
  • Hedef uç nokta yapılandırmalarını somut URL'lerden ayırmak için TargetServer kaynaklarını kullanın. Bu sayede, ortamlar arasında tanıtım yapabilirsiniz.
    Arka uç sunucularında yük dengeleme bölümüne bakın.
  • Birden fazla RouteRule'unuz varsa birini "varsayılan" olarak, yani koşul içermeyen bir RouteRule olarak oluşturun. Varsayılan RouteRule'un koşullu Rotalar listesinde en son tanımlandığından emin olun. RouteRule'lar, ProxyEndpoint'te yukarıdan aşağıya doğru değerlendirilir.
    API proxy yapılandırma referansı bölümüne bakın.
  • API proxy paketi boyutu: API proxy paketleri 15 MB'tan büyük olamaz. Apigee Edge for Private Cloud'da, aşağıdaki konumlarda thrift_framed_transport_size_in_mb özelliğini değiştirerek boyut sınırlamasını değiştirebilirsiniz: cassandra.yaml (Cassandra'da) ve conf/apigee/management-server/repository.properties.
  • API sürüm oluşturma: Apigee'nin API sürüm oluşturma ile ilgili düşünceleri ve önerileri için Web API Tasarımı: Eksik Bağlantı e-kitabındaki Sürüm Oluşturma bölümüne bakın.

CORS'u etkinleştirme

API'lerinizi yayınlamadan önce, istemci tarafı merkezler arası kaynak isteklerini desteklemek için API proxy'lerinizde CORS'u etkinleştirmeniz gerekir.

CORS (Merkezler arası kaynak paylaşımı), bir web sayfasında yürütülen JavaScript XMLHttpRequest (XHR) çağrılarının, kaynak olmayan alanlardaki kaynaklarla etkileşim kurmasına olanak tanıyan standart bir mekanizmadır. CORS, tüm tarayıcılar tarafından zorunlu kılınan aynı kaynak politikasına yönelik yaygın olarak uygulanan bir çözümdür. Örneğin, tarayıcınızda yürütülen JavaScript kodundan Twitter API'sine bir XHR çağrısı yaparsanız çağrı başarısız olur. Bunun nedeni, sayfayı tarayıcınıza sunan alan adının, Twitter API'sini sunan alan adıyla aynı olmamasıdır. CORS, sunucuların kaynaklar arası kaynak paylaşımı sağlamak istemeleri durumunda "etkinleştirmelerine" izin vererek bu soruna bir çözüm sunar.

API'leri yayınlamadan önce API proxy'lerinizde CORS'u etkinleştirme hakkında bilgi edinmek için API proxy'sine CORS desteği ekleme başlıklı makaleyi inceleyin.

İleti yükü boyutu

Edge'de bellek sorunlarını önlemek için ileti yükü boyutu 10 MB ile sınırlandırılmıştır. Bu boyutların aşılması protocol.http.TooBigBody hatasına neden olur.

Bu sorun bu Apigee topluluk gönderisinde de ele alınmıştır.

Edge'de büyük ileti boyutlarını işlemek için önerilen stratejiler şunlardır:

  • Akış istekleri ve yanıtları. Yayın yaptığınızda politikaların artık mesaj içeriğine erişemeyeceğini unutmayın. Akış istekleri ve yanıtları bölümünü inceleyin.
  • Edge for Private Cloud 4.15.07 ve önceki sürümlerinde, http.properties parametresindeki sınırı artırmak için mesaj işlemci HTTPResponse.body.buffer.limit dosyasını düzenleyin. Değişikliği üretime dağıtmadan önce test ettiğinizden emin olun.
  • Özel Bulut için Edge'in 4.16.01 ve sonraki sürümlerinde, yük içeren istekler Content-Length üst bilgisini veya akış durumunda "Transfer-Encoding: chunked" üst bilgisini içermelidir. Boş bir yük içeren bir API proxy'sine POST isteği gönderirken 0 Content-Length değeri iletmeniz gerekir.
  • Edge for Private Cloud 4.16.01 ve sonraki sürümlerde, sınırları değiştirmek için /opt/apigee/router.properties veya message-processor.properties dosyasında aşağıdaki özellikleri ayarlayın. Daha fazla bilgi için Yönlendiricide veya ileti işlemcisinde ileti boyutu sınırını ayarlama başlıklı makaleyi inceleyin.

    Her iki özelliğin de varsayılan değeri 10 MB'a karşılık gelen "10 m"dir:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Hata İşleme

  • Tüm hata yönetimi işlemlerini yönetmek için FaultRules'u kullanın. (RaiseFault politikaları, mesaj akışını durdurmak ve işleme sürecini FaultRules akışına göndermek için kullanılır.)
  • FaultRules akışında, hata yanıtını oluşturmak için RaiseFault politikalarını değil, AssignMessage politikalarını kullanın. Hata türüne göre AssignMessage politikalarını koşullu olarak yürütün.
  • Sistemin oluşturduğu hataların müşteri tarafından tanımlanan hata yanıtı biçimleriyle eşlenebilmesi için her zaman varsayılan bir "her şeyi yakalayan" hata işleyici içerir.
  • Mümkünse hata yanıtlarını her zaman şirketinizde veya projenizde bulunan standart biçimlerle eşleştirin.
  • Hata durumuna çözüm öneren, anlamlı ve kullanıcıların okuyabileceği hata mesajları kullanın.

Hataları ele alma başlıklı makaleyi inceleyin.

Sektördeki en iyi uygulamalar için RESTful hata yanıtı tasarımı başlıklı makaleyi inceleyin.

Kalıcılık

Anahtar/değer eşlemeleri

  • Anahtar/değer eşlemelerini yalnızca sınırlı veri kümeleri için kullanın. Uzun süreli veri depolama alanı olarak tasarlanmamıştır.
  • Bu bilgiler Cassandra veritabanında saklandığından anahtar/değer haritalarını kullanırken performansı göz önünde bulundurun.

Anahtar/Değer Çifti Eşleme İşlemleri Politikası'nı inceleyin.

Yanıt önbelleğe alma

  • Yanıt başarılı değilse veya istek bir GET değilse yanıt önbelleğini doldurmayın. Oluşturma, güncelleme ve silme işlemleri önbelleğe alınmamalıdır. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Önbelleği tek bir tutarlı içerik türüyle (ör. XML veya JSON) doldurun. Bir responseCache girişi alındıktan sonra JSONtoXML veya XMLToJSON ile gerekli içerik türüne dönüştürün. Bu sayede iki, üç veya daha fazla veri depolanması önlenir.
  • Önbellek anahtarının, önbelleğe alma koşulunu karşıladığından emin olun. Çoğu durumda request.querystring, benzersiz tanımlayıcı olarak kullanılabilir.
  • Açıkça gerekmedikçe API anahtarını (client_id) önbellek anahtarına eklemeyin. Çoğu zaman, yalnızca anahtarla güvenliği sağlanan API'ler, belirli bir istek için tüm istemcilere aynı verileri döndürür. API anahtarına göre bir dizi giriş için aynı değeri depolamak verimli değildir.
  • Eski verilerin okunmasını önlemek için uygun önbellek geçerlilik aralıkları ayarlayın.
  • Mümkün olduğunda, önbelleği dolduran yanıt önbelleği politikasının ProxyEndpoint yanıtı PostFlow'da mümkün olduğunca geç yürütülmesini sağlayın. Diğer bir deyişle, JavaScript tabanlı aracılık ve JSON ile XML arasında dönüştürme dahil olmak üzere çeviri ve aracılık adımlarından sonra yürütülmesini sağlayın. Aracılık edilen verileri önbelleğe alarak, önbelleğe alınmış verileri her aldığınızda aracılık adımını yürütmenin performans maliyetinden kaçınırsınız.

    Aracılık, istekten isteğe farklı bir yanıtla sonuçlanıyorsa aracılık edilmeyen verileri önbelleğe almanın daha iyi olabileceğini unutmayın.

  • Önbellek girişini aramak için yanıt önbelleği politikası, ProxyEndpoint isteği PreFlow'da gerçekleşmelidir. Önbellek girişi döndürmeden önce önbellek anahtarı oluşturma dışında çok fazla mantık uygulamaktan kaçının. Aksi takdirde, önbelleğe almanın faydaları en aza indirilir.
  • Genel olarak, yanıt önbelleği aramasını her zaman istemci isteğine mümkün olduğunca yakın tutmanız gerekir. Bunun aksine, yanıt önbelleği doldurma işlemini istemci yanıtına mümkün olduğunca yakın tutmalısınız.
  • Bir proxy'de birden fazla farklı yanıt önbelleği politikası kullanırken her biri için ayrı davranış sağlamak üzere aşağıdaki yönergeleri uygulayın:
    • Her politikayı birbirini dışlayan koşullara göre yürütün. Bu, birden fazla yanıt önbelleği politikasından yalnızca birinin yürütülmesini sağlar.
    • Her yanıt önbelleği politikası için farklı önbellek kaynakları tanımlayın. Önbellek kaynağını, politikanın <CacheResource> öğesinde belirtirsiniz.

Yanıt önbelleği politikasına göz atın.

Politika ve özel kod

Politika mı yoksa özel kod mu?

  • Öncelikle yerleşik politikaları kullanın (mümkün olduğunda). Apigee politikaları güvenli, optimize edilmiş ve desteklenir. Örneğin, yük oluşturmak, yüklerden bilgi ayıklamak (XPath, JSONPath) vb. için mümkün olduğunda JavaScript yerine standart AssignMessage ve ExtractVariables politikalarını kullanın.
  • Python ve Java yerine JavaScript tercih edilir. Ancak birincil gereksinim performans ise JavaScript yerine Java kullanılmalıdır.

JavaScript

  • Apigee politikalarına kıyasla daha sezgisel bir yöntemse (ör. birçok farklı URI kombinasyonu için target.url ayarlanırken) JavaScript kullanın.
  • JSON nesnesinde yineleme ve Base64 kodlama/kod çözme gibi karmaşık yük ayrıştırma işlemleri.
  • JavaScript politikasında zaman sınırı olduğundan sonsuz döngüler engellenir.
  • Her zaman JavaScript adımlarını kullanın ve dosyaları jsc kaynaklar klasörüne yerleştirin. JavaScript politikası türü, kodu dağıtım sırasında önceden derler.

JavaScript ile API proxy'leri programlama başlıklı makaleyi inceleyin.

Java

  • Performans en yüksek öncelikliyse veya mantık JavaScript'te uygulanamıyorsa Java'yı kullanın.
  • Java kaynak dosyalarını kaynak kodu izlemeye dahil edin.

API proxy'lerinde Java'yı kullanma hakkında bilgi için Yanıtı Java çağrısıyla büyük harfe dönüştürme ve Java Callout politikası başlıklı makaleleri inceleyin.

Python

  • Kesinlikle gerekli olmadığı sürece Python kullanmayın. Python komut dosyaları, çalışma zamanında yorumlandığı için basit yürütmelerde performans darboğazlarına neden olabilir.

Komut dosyası ek bilgileri (Java, JavaScript, Python)

  • Genel bir try/catch veya eşdeğerini kullanın.
  • Anlamlı istisnalar oluşturun ve bunları hata yanıtlarında kullanmak üzere uygun şekilde yakalayın.
  • İstisnaları erken gönderin ve yakalayın. Tüm istisnaları işlemek için genel try/catch ifadesini kullanmayın.
  • Gerekirse null ve undefined kontrolleri yapın. Bunun ne zaman yapılacağına dair bir örnek, isteğe bağlı akış değişkenleri alınırken olabilir.
  • Bir komut dosyası açıklama metni içinde HTTP/S istekleri göndermekten kaçının. Bunun yerine, bağlantıları sorunsuz bir şekilde işlediği için Apigee ServiceCallout politikasını kullanın.

JavaScript

  • API Platform'daki JavaScript, E4X aracılığıyla XML'yi destekler.

JavaScript nesne modeline bakın.

Java

  • Mesaj yüklerine erişirken context.getMessage() yerine context.getResponseMessage veya context.getRequestMessage kullanmayı deneyin. Bu, kodun hem istek hem de yanıt akışlarında yükü alabilmesini sağlar.
  • Kitaplıkları Apigee Edge kuruluşuna veya ortamına aktarın ve bunları JAR dosyasına dahil etmeyin. Bu işlem, paketin boyutunu küçültür ve diğer JAR dosyalarının aynı kitaplık deposuna erişmesine olanak tanır.
  • JAR dosyalarını API proxy kaynakları klasörüne eklemek yerine Apigee kaynakları API'sini kullanarak içe aktarın. Bu, dağıtım sürelerini kısaltır ve aynı JAR dosyalarının birden fazla API proxy'si tarafından referans alınmasına olanak tanır. Bir diğer avantaj ise sınıf yükleyici izolasyonudur.
  • Kaynak işleme (ör. iş parçacığı havuzları oluşturma ve yönetme) için Java kullanmayın.

Yanıtı Java çağrısıyla büyük harflere dönüştürme başlıklı makaleyi inceleyin.

Python

  • Anlamlı istisnalar oluşturun ve bunları Apigee hata yanıtlarında kullanılmak üzere uygun şekilde yakalayın.

Python komut dosyası politikası başlıklı makaleyi inceleyin.

ServiceCallouts

  • Bir API proxy'sinde hizmet çağrısı kullanarak başka bir API proxy'sini çağırdığınız proxy zincirleme için birçok geçerli kullanım alanı vardır. Proxy zincirleme kullanıyorsanız aynı API proxy'sine geri yapılan "sonsuz döngü" yinelemeli çağrıları önlediğinizden emin olun.

    Aynı kuruluş ve ortamdaki proxy'ler arasında bağlantı oluşturuyorsanız gereksiz ağ yükünü önleyen yerel bir bağlantı uygulama hakkında daha fazla bilgi için API proxy'lerini birlikte zincirleme başlıklı makaleyi inceleyin.

  • AssignMessage politikasını kullanarak bir ServiceCallout istek mesajı oluşturun ve mesaj değişkenindeki istek nesnesini doldurun. (İstek yükü, yol ve yöntemin ayarlanması buna dahildir.)
  • Politikada yapılandırılan URL'nin protokol belirtimi gerektirmesi, URL'nin protokol kısmının (ör. https://) bir değişkenle belirtilemeyeceği anlamına gelir. Ayrıca, URL'nin alan kısmı ve URL'nin geri kalanı için ayrı değişkenler kullanmanız gerekir. Örneğin: https://{domain}/{path}
  • ServiceCallout için yanıt nesnesini ayrı bir mesaj değişkeninde saklayın. Daha sonra ileti değişkenini ayrıştırabilir ve diğer politikalar tarafından kullanılmak üzere orijinal ileti yükünü olduğu gibi bırakabilirsiniz.

Hizmet açıklama metni politikasına bakın.

Öğelere erişme

AccessEntity Politikası

  • Daha iyi performans için uygulamaları uygulama adına göre değil, uuid göre arayın.

Erişim varlığı politikasına bakın.

Günlük Kaydı

  • Paketler arasında ve aynı pakette ortak bir syslog politikası kullanın. Bu, tutarlı bir günlük biçimi sağlar.

MessageLogging politikasına bakın.

İzleme

Cloud müşterilerinin Apigee Edge'in (yönlendiriciler, mesaj işlemciler vb.) tek tek bileşenlerini kontrol etmesi gerekmez. Apigee'nin Global Operations ekibi, müşterinin durum denetimi istekleri doğrultusunda API durum denetimleriyle birlikte tüm bileşenleri kapsamlı bir şekilde izler.

Apigee Analytics

Analytics, hata yüzdeleri ölçüldüğünden kritik olmayan API izleme sağlayabilir.

Analytics gösterge tabloları başlıklı makaleyi inceleyin.

Trace

API Edge yönetim kullanıcı arayüzündeki izleme aracı, bir API'nin geliştirme veya üretim işlemi sırasında çalışma zamanı API sorunlarını ayıklamak için kullanışlıdır.

İzleme aracını kullanma başlıklı makaleyi inceleyin.

Güvenlik