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 hakkında bir dizi standart ve en iyi uygulamayı sunmaktır. Burada işlenen konular tasarım, kodlama, politika kullanımı, izleme ve hata ayıklamadır. Bilgiler, başarılı API programları uygulamak için Apigee ile çalışan geliştiricilerin deneyimleriyle toplanmıştır. Bu, yaşayan bir belgedir ve zaman zaman güncellenecektir.

Buradaki yönergelere ek olarak, Apigee Edge Antipatterns Topluluk gönderisini de yararlı bulabilirsiniz.

Geliştirme standartları

Yorumlar ve Belgeler

  • ProxyEndpoint ve TargetEndpoint yapılandırmalarında satır içi yorumlar sağlayın. Yorumlar, özellikle politika dosya adlarının Akışın temel işlevini açıklamak için yeterince açıklayıcı olmadığı durumlarda Akışın okunabilirliğini artırır.
  • Yorumları faydalı hale getirin. Bariz yorumlardan kaçının.
  • Tutarlı girinti, boşluk, dikey hizalama vb. kullanın.

Çerçeve stilinde kodlama

Çerçeve stili kodlamada, API proxy kaynaklarının yerel geliştirme ortamlarında tekrar kullanılması için kendi sürüm kontrol sisteminizde depolanması gerekir. Örneğin, bir politikayı yeniden kullanmak için kaynak kontrolünde depolayın. Böylece geliştiriciler senkronize ederek kendi proxy geliştirme ortamlarında kullanabilir.

  • Mümkün olduğunda DRY'yi ("kendinizi tekrarlamayın") etkinleştirmek için politika yapılandırmaları ve komut dosyaları, özelleştirilmiş, yeniden kullanılabilir işlevler uygulamalıdır. Örneğin, istek mesajlarından sorgu parametrelerinin çıkarılması için özel bir politika ExtractVariables.ExtractRequestParameters olarak adlandırılabilir. CORS üst bilgileri eklemek için özel bir politika AssignMessage.SetCORSHeaders olarak adlandırılmış olabilir. Daha sonra bu politikalar, kaynak kontrol sisteminizde depolanabilir ve gereksiz (ve dolayısıyla daha az yönetilebilir) yapılandırmalar oluşturmanıza gerek kalmadan parametreleri çıkarması veya CORS başlıklarını ayarlaması gereken her bir API proxy'sine eklenebilir.
  • Kullanılmayan politikaları ve kaynakları (JavaScript, Java, XSLT vb.) API proxy'lerinden, özellikle de içe aktarma ve dağıtım prosedürlerini yavaşlatma potansiyeli olan büyük kaynaklardan temizleyin.

Adlandırma Kuralları

  • Politika name özelliği ve XML politikası dosyasının adı aynı olmalıdır.
  • Komut Dosyası ve ServiceCall politikası name özelliği ile kaynak dosyanın adı aynı olmalıdır.
  • DisplayName, daha önce söz konusu API proxy'siyle 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 eklerin ardından tirelerle ayrılmış açıklayıcı kelimeler dizisi kullanın. Örneğin, assignMessage politikaları için AM-xxx. Ayrıca bkz. Apigeelint aracı.
  • Kaynak dosyalar için uygun uzantıları, 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. Deve Case veya alt_çizgi gibi bir stil seçerseniz bu stili API proxy'si genelinde kullanın.
  • Mümkün olduğunda değişken ön eklerini kullanarak değişkenleri amaçlarına göre düzenleyin (örneğin, Consumer.username ve Consumer.password).

API proxy'si geliştirme

Tasarımda Dikkat Edilmesi Gerekenler

  • RESTful API tasarımı hakkında yardım almak için Web API Design: The missing Link (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şula sahip olan çoklu Akışlar, aynı PreFlow ve Postflow'a birden fazla koşullu ek yerine tercih edilir.
  • "Hatalı" olarak / ProxyEndpoint BasePath değerine sahip 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 değerinin döndürülmesinden daha yararlı başka bir işlem gerçekleştirmek için kullanılabilir.
  • TargetEndpoint yapılandırmalarını somut URL'lerden ayırmak için TargetServer kaynaklarını kullanın, böylece ortamlar arasında tanıtımı destekleyin.
    Arka uç sunucular arasında yük dengeleme bölümünü inceleyin.
  • Birden fazla RouteKural'ınız varsa "varsayılan" olarak, yani koşulsuz bir RouteRule olarak oluşturun. Varsayılan RouteRule'ın koşullu Rotalar listesinde en son tanımlandığından emin olun. RouteRules, 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. Private Cloud için Apigee Edge'de şu konumlardaki 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/impression/management-server/repository.properties.
  • API sürümü oluşturma: Apigee'nin API sürümü oluşturmayla ilgili düşünceleri ve önerileri için Web API Design: The Missing Link (Web API Tasarımı: Eksik Bağlantı) e-kitabının Versioning (Sürüm Oluşturma) bölümüne bakın.

CORS'yi etkinleştirme

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

CORS (kaynaklar 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 uygulanan aynı kaynak politikası için yaygın olarak uygulanan bir çözümdür. Örneğin, tarayıcınızda çalışan JavaScript kodundan Twitter API'ye 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, kaynaklar arası kaynak paylaşımı sağlamak isteyen sunucuların "kaydolmasına" izin vererek bu soruna bir çözüm sunar.

API'leri yayınlamadan önce API proxy'lerinizde CORS'yi etkinleştirme hakkında bilgi edinmek için API proxy'sine CORS desteği ekleme sayfasına bakın.

Mesaj yükü boyutu

Edge'de bellek sorunlarını önlemek için mesaj 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 Topluluğu gönderisinde de ele alınmıştır.

Aşağıda, Edge'de büyük ileti boyutlarını işlemek için önerilen stratejiler verilmiştir:

  • İstek ve yanıtları akış şeklinde gösterme. Yayın sırasında politikaların artık mesaj içeriğine erişemeyeceğini unutmayın. İstekleri ve yanıtları akış şeklinde gösterme bölümünü inceleyin.
  • Private Cloud için Edge 4.15.07 ve önceki sürümlerde, HTTPResponse.body.buffer.limit parametresindeki sınırı artırmak için mesaj işlemci http.properties dosyasını düzenleyin. Değişikliği üretime dağıtmadan önce test etmeyi unutmayın.
  • Private Cloud için Edge 4.16.01 ve sonraki sürümlerde yük içeren isteklerde Content-Length (İçerik Uzunluğu) başlığını veya "Transfer-Encoding: chunked" üstbilgisini içermesi gerekir. Boş yüke sahip bir API proxy'sine POST göndermek için 0 İçerik Uzunluğunu iletmeniz gerekir.
  • Private Cloud için Edge 4.16.01 ve sonraki sürümlerde, sınırları değiştirmek üzere /opt/Apigee/router.properties veya message-processor.properties dosyasında aşağıdaki özellikleri ayarlayın. Daha fazla bilgi için Yönlendirici veya Mesaj İşleyici'de mesaj boyutu sınırını ayarlama bölümüne bakın.

    Her iki özellik de 10 MB'a karşılık gelen varsayılan "10m" değerine sahiptir:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Arıza İşleme

  • Tüm hata işleme sorunlarını çözmek için FaultRules'dan yararlanın. (GrowFault politikaları, mesaj Akışı'nı durdurmak ve işlemeyi FaultRules Akışı'na göndermek için kullanılır.)
  • FaultRules Akışı'nda, hata yanıtını oluşturmak için PromoteMessage politikalarını kullanın. Atayın politikalarını ortaya çıkan hata türüne göre koşullu olarak yürütün.
  • Sistem tarafından oluşturulan hataların, müşteri tarafından tanımlanan hata yanıtı biçimleriyle eşleştirilebilmesi için her zaman varsayılan bir "tümünü yakala" hata işleyicisi içerir.
  • Mümkünse hatalı yanıtların her zaman şirketinizde veya projenizde bulunan standart biçimlerle uyumlu olmasını sağlayın.
  • Hata durumuna çözüm öneren anlamlı, okunabilir hata mesajları kullanın.

Hataları işleme bölümüne bakın.

Sektör en iyi uygulamaları için RESTful hata yanıtı tasarımı konusuna bakın.

Kalıcı

Anahtar/Değer Eşlemeleri

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

Anahtar Değer 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. BirResponseCache girişi aldıktan sonra, JSONtoXML veya XMLToJSON ile gereken içerik türüne dönüştürün. Bu seçenek iki, üç veya daha fazla verinin depolanmasını önler.
  • Önbellek anahtarının, önbelleğe alma gereksinimi için yeterli olduğundan emin olun. Çoğu durumda, benzersiz tanımlayıcı olarak request.querystring kullanılabilir.
  • Açıkça gerekli olmadığı sürece API anahtarını (client_id) önbellek anahtarına eklemeyin. Yalnızca anahtarla güvenliği sağlanan API'ler çoğu zaman belirli bir istek için tüm istemcilere aynı verileri döndürür. API anahtarını temel alan çok sayıda giriş için aynı değerin depolanması verimsizdir.
  • Kirli okumalardan kaçınmak için uygun önbellek son kullanma aralıklarını ayarlayın.
  • Mümkün olduğunda önbelleği dolduran yanıt önbellek politikasının mümkün olduğunca geç ProxyEndpoint yanıtı PostFlow'da yürütülmesini sağlayın. Bir başka deyişle, JavaScript tabanlı uyumlulaştırma ve JSON ile XML arasında dönüşüm dahil olmak üzere çeviri ve uyumlulaştırma adımlarından sonra çalışmasını sağlayın. Uyumlulaştırılmış verileri önbelleğe alarak, önbelleğe alınan verileri her aldığınızda uyumlulaştırma adımını yürütmenin performans maliyetinden kurtulmuş olursunuz.

    Uyumlulaştırmanın istekten isteğe farklı bir yanıtla sonuçlanması durumunda, aracı olmayan verileri önbelleğe almak isteyebilirsiniz.

  • Önbellek girişini aramak için yanıt önbellek politikası, ProxyEndpoint isteği PreFlow'da bulunmalıdır. Bir ö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 iner.
  • Genel olarak, yanıt önbelleği aramasını her zaman istemci isteğine mümkün olduğunca yakın tutmalısınız. Buna karşılık, yanıt önbelleği popülasyonunu istemci yanıtına mümkün olduğunca yakın tutmanız gerekir.
  • Bir proxy'de birden fazla yanıt önbelleği politikası kullanırken her politika için ayrı bir davranış sağlamak üzere aşağıdaki yönergeleri uygulayın:
    • Her politikayı, karşılıklı olarak birbirini dışlayan koşullara göre yürütün. Bu, birden fazla yanıt önbellek politikasından yalnızca birinin yürütülmesine yardımcı olur.
    • Her yanıt önbellek politikası için farklı önbellek kaynakları tanımlayın. Önbellek kaynağını politikanın <CacheResource> öğesinde belirtirsiniz.

Yanıt Önbelleği politikasını inceleyin.

Politika ve özel kod

Politika mı, özel kod mu?

  • Öncelikle ve mümkün olduğunda yerleşik politikaları kullanın. Apigee politikaları sağlamlaştırılmış, optimize edilmiştir ve desteklenir. Örneğin, yük oluşturmak, yüklerden bilgileri ayıklamak (XPath, JSONPath) vb. için JavaScript (mümkünse) yerine standart AtaMessage ve ExtractVariables politikalarını kullanın.
  • Python ve Java yerine JavaScript tercih edilir. Ancak, birincil gereksinim performanssa JavaScript yerine Java kullanılmalıdır.

JavaScript

  • Apigee politikalarından daha sezgiselyse (örneğin, birçok farklı URI kombinasyonu için target.url ayarlarken) JavaScript kullanın.
  • Bir JSON nesnesi üzerinden yineleme ve Base64 kodlaması/kod çözme gibi karmaşık yük ayrıştırma.
  • JavaScript politikasının bir 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 Politika türü, dağıtım sırasında kodu önceden derler.

JavaScript ile API proxy'lerini programlama bölümünü inceleyin.

Java

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

API proxy'lerinde Java kullanımı hakkında bilgi için Yanıtı Java çağrısıyla büyük harfe dönüştürme ve Java Açıklama metni politikası bölümlerine bakın.

Python

  • Mutlaka gerekli olmadığı sürece Python kullanmayın. Python komut dosyaları, çalışma zamanında yorumlandığı için basit yürütme işlemleri için performans performans sorunlarını beraberinde getirebilir.

Komut Dosyası Açıklama Metinleri (Java, JavaScript, Python)

  • Global bir dene-yakala veya eşdeğeri kullanın.
  • Anlamlı istisnaları koyun ve bunları hatalı yanıtlarda kullanmak üzere uygun şekilde yakalayın.
  • İstisnaları erkenden belirleyin ve yakalayın. Tüm istisnaları işlemek için genel dene-yakala yöntemini kullanmayın.
  • Gerektiğinde boş ve tanımlanmamış denetimler gerçekleştirin. Bunun ne zaman yapılacağına örnek olarak isteğe bağlı akış değişkenlerinin alınması verilebilir.
  • Komut dosyası açıklama metni içinde HTTP/S istekleri oluşturmaktan kaçının. Bunun yerine, politika bağlantıları sorunsuz bir şekilde ele aldığından Apigee ServiceCall politikasını kullanın.

JavaScript

  • API Platformu'ndaki JavaScript, E4X üzerinden XML'i destekler.

JavaScript nesne modeli bölümüne bakın.

Java

  • Mesaj yüklerine erişirken, context.getResponseMessage veya context.getRequestMessage yerine context.getMessage() 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 eklemeyin. Bu işlem, paket boyutunu küçültür ve diğer JAR dosyalarının aynı kitaplık deposuna erişmesine izin verir.
  • JAR dosyalarını API proxy kaynakları klasörüne eklemek yerine Apigee Resources API'yi kullanarak içe aktarın. Bu, dağıtım sürelerini kısaltır ve aynı JAR dosyalarına birden fazla API proxy'si tarafından referans verilmesini sağlar. Diğer bir avantaj da sınıf yükleyici izolasyonudur.
  • Kaynak işleme (örneğin, iş parçacığı havuzları oluşturma ve yönetme) için Java kullanmayın.

Yanıtı Java çağrısıyla büyük harfe dönüştürme bölümüne bakın.

Python

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

Python Komut Dosyası politikasını inceleyin.

ServiceCallouts

  • Proxy zincirleme kullanımına ilişkin birçok geçerli kullanım alanı vardır. Bu kullanımlarda, başka bir API proxy'sini çağırmak için bir API proxy'sinde bir hizmet çağrısı kullanırsınız. Proxy zincirleme kullanıyorsanız aynı API proxy'sine gelen "sonsuz döngü" yinelemeli çağrılardan kaçındığınızdan emin olun.

    Aynı kuruluş ve ortamdaki proxy'ler arasında bağlantı kuruyorsanız gereksiz ağ ek yükünü önleyen yerel bağlantı uygulama hakkında daha fazla bilgi için API proxy'lerini birbirine bağlama bölümünü inceleyin.

  • AttributionMessage politikasını kullanarak bir ServiceDescription istek mesajı oluşturun ve istek nesnesini bir mesaj değişkenine doldurun. (Buna istek yükünü, yolunu ve yöntemini ayarlama da dahildir.)
  • Politika içinde yapılandırılan URL, protokol spesifikasyonunu gerektirir. Diğer bir deyişle URL'nin protokol kısmı (örneğin, https://) bir değişken tarafından belirtilemez. Ayrıca, URL'nin alan adı kısmı ve URL'nin geri kalanı için ayrı değişkenler kullanmanız gerekir. Örneğin: https://{domain}/{path}
  • ServiceCall'un yanıt nesnesini ayrı bir mesaj değişkeninde depolayın. Ardından mesaj değişkenini ayrıştırabilir ve orijinal mesaj yükünü diğer politikalar tarafından kullanılmak üzere koruyabilirsiniz.

Hizmet açıklama metni politikasını inceleyin.

Varlıklara erişme

AccessEntity Politikası

  • Daha iyi performans için uygulamaları uygulama adı yerine uuid bazında arayın.

Varlık Erişimi Politikası'nı inceleyin.

Günlük Kaydı

  • Paketler arasında ve aynı paket içinde ortak bir sistem günlüğü politikası kullanın. Bu, tutarlı bir günlük kaydı biçimi sağlar.

MessageLogging politikasına bakın.

İzleme

Cloud müşterilerinin Apigee Edge'in her bileşenini (Yönlendiriciler, Mesaj İşleyiciler vb.) ayrı ayrı kontrol etmesi gerekmez. Apigee'nin Küresel Operasyon ekibi, müşteriden gelen durum denetimi istekleri doğrultusunda API durum denetimlerinin yanı sıra tüm bileşenleri ayrıntılı bir şekilde izlemektedir.

Apigee Analizi

Analytics, hata yüzdeleri ölçülürken kritik olmayan API izlemesi sağlayabilir.

Analytics kontrol panellerini 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