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. info

Bu belgenin amacı, Apigee Edge ile geliştirme yapmayla ilgili bir dizi standart ve en iyi uygulama sunmaktır. Burada tasarım, kodlama, politika kullanımı, izleme ve hata ayıklama gibi konular ele alınmaktadır. Bu bilgiler, başarılı API programları uygulamak için Apigee ile çalışan geliştiricilerin deneyimlerinden derlenmiştir. Bu, zaman zaman güncellenecek olan dinamik bir belgedir.

Buradaki kurallara ek olarak Apigee Edge Antipatterns (Apigee Edge Antipatterns) topluluğu tarafından yayınlanan makaleyi de faydalı bulabilirsiniz.

Geliştirme standartları

Yorumlar ve Dokümanlar

  • 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 ifade edecek kadar açıklayıcı olmadığı durumlarda akışın okunabilirliğini artırır.
  • Yorumların yararlı olmasına özen gösterin. Açıkça anlaşılan yorumlardan kaçının.
  • Tutarlı girinti, boşluk, dikey hizalama vb. kullanın.

Çerçeve stili kodlama

Çerçeve tarzı kodlama, API proxy kaynaklarını yerel geliştirme ortamlarında yeniden kullanmak için kendi sürüm kontrol sisteminizde saklamayı içerir. Örneğin, bir politikayı yeniden kullanmak için geliştiricilerin kendi proxy geliştirme ortamlarında senkronize edip kullanabilmesi amacıyla politikayı kaynak denetiminde depolayın.

  • DRY ("kendinizi tekrarlamayın") özelliğini etkinleştirmek için mümkün olduğunda politika yapılandırmaları ve komut dosyalarında özel, yeniden kullanılabilir işlevler uygulanmalıdır. Örneğin, istek mesajlarından sorgu parametrelerini ayıklamak için özel bir politika ExtractVariables.ExtractRequestParameters olarak adlandırılabilir. CORS başlıkları eklemek için özel bir politika AssignMessage.SetCORSHeaders olarak adlandırılabilir. Bu politikalar daha sonra kaynak denetimi sisteminizde saklanabilir ve parametreleri çıkarması veya CORS üstbilgilerini ayarlaması gereken her API proxy'sine eklenebilir. Bu işlem için 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 de içe aktarma ve dağıtma işlemlerini yavaşlatabilecek büyük kaynakları temizleyin.

Adlandırma Kuralları

  • Politika name özelliği ve XML politika dosyası adı aynı olmalıdır.
  • Komut dosyası ve Hizmet Açıklaması politikası name özelliği ile kaynak dosyasının adı aynı olmalıdır.
  • DisplayName, politikanın işlevini daha önce bu API proxy'siyle hiç çalışmamış birine 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 kısa çizgiyle ayrılmış açıklayıcı kelimeler kullanın. Örneğin, AssignMessage politikaları için AM-xxx. apigeelint aracına da göz atın.
  • Kaynak dosyaları için uygun uzantıları kullanın: JavaScript için .js, Python için .py ve Java JAR dosyaları için .jar.
  • Değişken adları tutarlı olmalıdır. camelCase veya under_score gibi bir stil seçerseniz API proxy'sinde bu stili kullanın.
  • Mümkün olduğunda değişkenleri amaçlarına göre düzenlemek için değişken ön ekleri kullanın (ör. Consumer.username ve Consumer.password).

API proxy'si geliştirme

İlk Tasarımla İlgili Dikkat Edilmesi Gereken Noktalar

  • RESTful API tasarımı hakkında bilgi edinmek için Web API Design: The Missing Link (Web API Tasarımı: Eksik Halka) e-kitabını 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 birden çok akış, aynı ön akışa ve son akışa yönelik birden çok koşullu ekliğe tercih edilir.
  • "Güvenli bir yedek" olarak, ProxyEndpoint BasePath değeri / olan varsayılan bir 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.
  • TargetEndpoint yapılandırmalarını belirli URL'lerden ayırmak için TargetServer kaynaklarını kullanarak ortamlar arasında promosyonu destekleyin.
    Arka uç sunucularında yük dengeleme başlıklı makaleyi inceleyin.
  • Birden fazla RouteRule'unuz varsa "varsayılan" olarak bir tane oluşturun. Yani koşul içermeyen bir RouteRule oluşturun. Varsayılan RouteRule'ın koşullu yollar listesinde en son tanımlandığından emin olun. RouteRules, ProxyEndpoint'te yukarıdan aşağıya doğru değerlendirilir.
    API proxy'si 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, thrift_framed_transport_size_in_mb mülkünü aşağıdaki konumlarda 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ümlendirme: Apigee'nin API sürümlendirmeyle ilgili görüşleri ve önerileri için Web API Design: The Missing Link (Web API Tasarımı: Eksik Halka) e-kitabındaki Sürümlendirme bölümüne bakın.

CORS'yi etkinleştirme

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

CORS (Merkekler 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şime girmesine olanak tanıyan standart bir mekanizmadır. CORS, tüm tarayıcılar tarafından zorunlu kılınan aynı kaynak politikası için yaygın olarak uygulanan bir çözümdür. Örneğin, tarayıcınızda çalıştırılan JavaScript kodundan Twitter API'ye XHR çağrısı yaparsanız çağrı başarısız olur. Bunun nedeni, sayfayı tarayıcınıza sunan alanın Twitter API'yi sunan alanla aynı olmamasıdır. CORS, sunucuların merkezler arası kaynak paylaşımı sağlamak isterse "etkinleştirmesine" 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ırlıdır. Bu boyutların aşılması protocol.http.TooBigBody hatasıyla sonuçlanır.

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

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

  • Akış istekleri ve yanıtları. Canlı yayın yaparken politikaların mesaj içeriğine erişemediğini unutmayın. İstek ve yanıt akışı başlıklı makaleyi 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şleyici http.properties dosyasını düzenleyin. Değişikliği üretime dağıtmadan önce test ettiğinizden emin olun.
  • Private Cloud için Edge 4.16.01 ve sonraki sürümlerde, yükü olan istekler Content-Length üstbilgisini veya akış durumunda "Transfer-Encoding: chunked" üstbilgisini içermelidir. Boş bir yük içeren bir API proxy'sine POST göndermek için Content-Length parametresini 0 olarak göndermeniz gerekir.
  • Özel Bulut için Edge 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şleyicide ileti boyutu sınırını belirleme başlıklı makaleyi inceleyin.

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

Hata İşleme

  • Tüm hata işlemlerini yönetmek için FaultRules'den yararlanın. (RaiseFault politikaları, mesaj akışını durdurmak ve işlemeyi FaultRules akışına göndermek için kullanılır.)
  • Hata kuralları akışında, hata yanıtını oluşturmak için RaiseFault politikalarını değil, AssignMessage politikalarını kullanın. AssignMessage politikalarını, gerçekleşen hata türüne göre koşullu olarak yürütme.
  • Sistem tarafından oluşturulan hataların müşteri tanımlı 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 projenizdeki standart biçimlerle eşleşecek şekilde ayarlayın.
  • Hata durumuna yönelik çözüm önerisi sunan, anlamlı ve kullanıcıların okuyabileceği hata mesajları kullanın.

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

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

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 süreli veri deposu olarak tasarlanmamıştır.
  • Bu bilgiler Cassandra veritabanında depolandığından anahtar/değer haritalarını 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 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. responseCache girişini aldıktan sonra JSONtoXML veya XMLToJSON ile gerekli içerik türüne dönüştürün. Bu sayede, aynı verilerin iki, üç veya daha fazla kopyası depolanmaz.
  • Önbellek anahtarının, önbelleğe alma koşulunu karşıladığından emin olun. Birçok durumda request.querystring, benzersiz tanımlayıcı olarak kullanılabilir.
  • API anahtarını (client_id), açıkça gerekli olmadığı sürece önbellek anahtarına eklemeyin. Yalnızca bir anahtarla korunan API'ler genellikle 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.
  • Kirli okumaları önlemek için uygun önbellek süre sonu aralıkları belirleyin.
  • Mümkün olduğunda, önbelleği dolduran yanıt önbelleği politikasının ProxyEndpoint yanıtı Son Akış'ında mümkün olduğunca geç saatte yürütülmesini deneyin. Diğer bir 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ıştırın. Aracılık yapılan verileri önbelleğe alarak, önbelleğe alınmış verileri her aldığınız

    Uyumlulaştırma, isteklerden farklı yanıtlarla sonuçlanıyorsa bunun yerine uyumlulaştırılmamış verileri önbelleğe almak isteyebilirsiniz.

  • Önbelleğe alınmış girişi arayan yanıt önbelleği politikası, ProxyEndpoint istek ön akışında 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 alma avantajları 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. Buna karşılık, yanıt önbelleği nüfusunu 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ı bir davranış sağlamak amacıyla aşağıdaki yönergeleri uygulayın:
    • Her bir politikayı birbirini hariç tutan 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. Politikanın <CacheResource> öğesinde önbelleğe alma kaynağını belirtirsiniz.

Yanıt Önbelleği Politikası'nı inceleyin.

Politika ve özel kod

Politika mı yoksa özel kod mu?

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

JavaScript

  • Apigee politikalarından daha sezgiselse JavaScript'i kullanın (örneğin, birçok farklı URI kombinasyonu için target.url ayarlama yaparken).
  • JSON nesnesi içinde iterasyon ve Base64 kodlama/kod çözme gibi karmaşık yük ayrıştırma işlemleri
  • JavaScript politikasının 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 koyun. 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 önceliğe sahipse veya mantık JavaScript'te uygulanamıyorsa Java'yı kullanın.
  • Java kaynak dosyalarını kaynak kod izlemeye dahil edin.

API proxy'lerinde Java kullanımı hakkında bilgi edinmek için Yanıtı Java açıklama metniyle büyük harflere dönüştürme ve Java açıklama metni 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 yol açabilir.

Komut dosyası açıklamaları (Java, JavaScript, Python)

  • Global bir try/catch veya eşdeğeri kullanın.
  • Anlamlı istisnalar oluşturun ve bunları hata yanıtlarında kullanmak için uygun şekilde yakalayın.
  • İstisnaları erken gönderin ve yakalayın. Tüm istisnaları işlemek için genel try/catch kullanmayın.
  • Gerekirse null ve undefined kontrolleri yapın. Bu işlemin ne zaman yapılacağına dair bir örnek, isteğe bağlı akış değişkenlerini alma işlemidir.
  • Komut dosyası açıklama metni içinde HTTP/S isteği göndermekten kaçının. Bunun yerine, bağlantıları sorunsuz bir şekilde ele aldığı için Apigee ServiceCallout politikasını kullanın.

JavaScript

  • API Platformu'ndaki JavaScript, E4X aracılığıyla XML'i destekler.

JavaScript nesne modeline bakın.

Java

  • İleti yüklerine erişirken context.getMessage() yerine context.getResponseMessage veya context.getRequestMessage kullanmayı deneyin. Bu sayede kod, hem istek hem de yanıt akışlarında yükü alabilir.
  • Kitaplıkları Apigee Edge kuruluşuna veya ortamına aktarın ve bunları JAR dosyasına dahil etmeyin. Bu işlem, paket boyutunu azaltı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 dahil etmek yerine Apigee resources API'yi 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 almasına olanak tanır. Bir diğer avantaj da sınıf yükleyici izolasyonudur.
  • Kaynakları işlemek için Java kullanmayın (ör. iş parçacığı havuzları oluşturma ve yönetme).

Java açıklama metniyle yanıtı büyük harfli olarak dönüştürme başlıklı makaleyi inceleyin.

Python

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

Python Komut Dosyası Politikası'nı inceleyin.

ServiceCallouts

  • Bir API proxy'sinde başka bir API proxy'sini çağırmak için hizmet açıklama metni kullandığınız proxy zincirleme işleminin birçok geçerli kullanım alanı vardır. Proxy zincirleme kullanıyorsanız aynı API proxy'sine geri dönen "sonsuz döngü" yinelenen açıklama metinlerinden kaçının.

    Aynı kuruluş ve ortamda bulunan proxy'ler arasında bağlantı kuruyorsanız gereksiz ağ yükü oluşturmayan yerel bir bağlantı oluşturma hakkında daha fazla bilgi edinmek için API proxy'lerini birbirine bağlama başlıklı makaleyi inceleyin.

  • AssignMessage politikasını kullanarak bir ServiceCallout istek mesajı oluşturun ve istek nesnesini bir mesaj değişkeninde doldurun. (İstek yükü, yolu ve yöntemini ayarlama da buna dahildir.)
  • Politika içinde yapılandırılan URL, protokol spesifikasyonunu gerektirir. Bu, URL'nin protokol kısmının (ör. https://) bir değişkenle belirtilemeyeceği anlamına gelir. 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}
  • ServiceCallout için yanıt nesnesini ayrı bir mesaj değişkeninde saklayın. Ardından, mesaj değişkenini ayrıştırabilir ve diğer politikalar tarafından kullanılması için orijinal mesaj yükünü bozulmadan koruyabilirsiniz.

Hizmet Çağrısı Politikası'na bakın.

Öğelere erişme

AccessEntity Politikası

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

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

Günlük Kaydı

  • Paketler arasında ve aynı paket içinde ortak bir syslog politikası kullanın. Bu sayede tutarlı bir günlük kaydı biçimi elde edilir.

Mesaj Günlüğe Kaydetme Politikası'nı inceleyin.

İzleme

Cloud müşterilerinin Apigee Edge'in bileşenlerini (yönlendiriciler, mesaj işleyiciler vb.) tek tek kontrol etmesi gerekmez. Apigee'nin Küresel Operasyon Ekibi, müşteri tarafından verilen durum denetimi isteklerinin yanı sıra API durum denetimleriyle birlikte tüm bileşenleri ayrıntılı bir şekilde izler.

Apigee Analytics

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

Analytics kontrol panelleri başlıklı makaleyi inceleyin.

Trace

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

İzleme aracını kullanma başlıklı makaleye göz atın.

Güvenlik