Bir API, başka bir uygulamanın entegrasyonunuzu hangi adres ve veri biçimiyle çağıracağını tanımlar. Lunex’te API sözleşmesini oluşturur, her işlemi bir akışa bağlar, örnek veya gerçek isteklerle dener ve erişim koşullarıyla birlikte yayımlarsınız.
Örneğin bir sipariş API’si POST /orders isteğini alabilir; akış veriyi kontrol eder, dönüştürür, bir sisteme iletir ve sonucu çağırana döndürür. İşlemi kuyruğa bırakmak istiyorsanız akışta mesajlaşma bağlantısı kullanabilirsiniz. Böyle bir tasarımda API’nin verdiği kabul yanıtıyla arka plandaki işin tamamlanması farklı sonuçlardır.
Nereden başlamalısınız?
| İhtiyacınız | Okuma yolu |
|---|---|
| Hazır bir projeyi açıp denemek istiyorum | İndirilebilir örnek projeler |
| REST ve HTTP kavramlarını öğreniyorum | REST servisi ve isteğin yolculuğu → ilk API |
| Bir API’yi sıfırdan çalıştırmak istiyorum | İlk API → sipariş API’si örneği |
| Elimde OpenAPI dosyası var | OpenAPI desteği ve içe alma → operation ve route bağı |
| Girdileri ve ortak modelleri yönetiyorum | Şema ve doğrulama → doğru ve hatalı istek denemeleri |
| Birkaç işlem aynı hata yapısını kullansın istiyorum | Üç işlemde ortak hata modeli → tasarımda iyi uygulamalar |
| API’yi başka bir uygulama çağıracak | Kimlik ve yetkilendirme → test ve yayınlama |
| Çağrım beklediğim sonucu vermiyor | API hata teşhisi |
| Ayarların etkisini veya nasıl yardım isteyeceğimi anlamak istiyorum | Sorular ve çalışma ipuçları |
İlk iki anlatım için çalışan bir dış sistem gerekmez. Sipariş örneği, gösterim verisiyle gerçek route çalıştırır; şema hatası ile iş kuralı hatasının farkını gösterir. Dış erişim adımına geçtiğinizde ortam adresi ve güvenlik kaynaklarını ayrıca hazırlarsınız.
API’yi oluşturan parçalar
| Parça | Anlamı | Lunex’teki yeri |
|---|---|---|
| Proje | Birlikte geliştirdiğiniz, çalıştırdığınız ve dağıttığınız entegrasyon dosyaları | Projects |
| API sözleşmesi | Adresler, HTTP yöntemleri, girdiler, yanıtlar ve veri modelleri | Projedeki openapi.json, API design |
| Operation | Belirli bir yöntem ve yol için çağrılabilir işlem | Örneğin GET /orders/{orderId}, Operation ID: getOrder |
| İş akışı | İşlemin gerçekten yaptığı iş | direct:getOrder ile başlayan route |
| Schema | Bir verinin türleri ve kuralları | Components → Schemas veya işlem içindeki schema |
| Erişim ayarı | API’nin dışarı açılması, HTTP/HTTPS ve kimlik doğrulama politikası | API access; proje dosyası api-publishing.yaml |
| Çalışan sürüm | İstekleri şu anda karşılayan geliştirme veya deployment runtime’ı | Proje durumu ve API access → Publication |
Operation ID, route ID ve dosya adı farklı amaçlar taşır. getOrder işlemi direct:getOrder girişini çağırır; bu route’un adı order-lookup, bulunduğu dosya orders.camel.yaml olabilir. Bağı kuran değer Direct girişidir.
Hangi işi hangi ekranda yaparsınız?
- İlk API’yi oluşturun veya bir sözleşmeyi içe alın.
- İşlemleri, parametreleri ve route bağını tanımlayın.
- İstek ve yanıt modellerini hazırlayın.
- Erişim politikasını ve kimlik doğrulamayı seçin.
- API’yi deneyin ve yayımlayın.
Bir API projesinin Architecture görünümü, API ile iş akışları arasındaki ilişkileri gösterir. API design sözleşmeyi düzenler; Source → Files aynı projenin route, properties, Java ve diğer dosyalarını yönetir. API sözleşmesini değiştirirken iş akışını da aynı proje içinde geliştirirsiniz.
Sözleşme, uygulama ve erişim birlikte çalışır
Çağrı sırası genel olarak şöyledir:
- İstemci yayımlanan proje adresine istek gönderir.
- Erişim katmanı seçtiğiniz kimlik doğrulama politikasını uygular.
- Çalışan API, desteklenen istek kurallarını kontrol eder.
- İlgili
direct:<operationId>route’u iş mantığını çalıştırır. - Route’un ürettiği durum kodu, içerik türü ve gövde istemciye döner.
Sözleşmeye bir yanıt yazmak o yanıtı üreten iş mantığını oluşturmaz. Benzer şekilde sözleşmeye security tanımı eklemek tek başına erişimi korumaz. İstek doğrulaması, route davranışı ve API access ayarları ayrı ayrı tamamlanmalıdır.
Kullanabileceğiniz yetenekler
Lunex; JSON biçimindeki OpenAPI 3.0/3.1 sözleşmeleri, Form/Source düzenleme, yerel referanslar ve ortak schema’lar, işlem başına istek/yanıt tanımları, tarayıcıda Mock, çalışan geliştirme projesinde gerçek çağrı, Git üzerinden deployment ve proje API’sine Basic/API key/JWT erişim politikalarını kapsar.
Çalıştırılabilir API tasarlarken GET, POST, PUT, PATCH ve DELETE kullanın. İstek parametrelerinde path/query/header konumlarını ve tekil string/integer/number/boolean değerlerini tercih edin. Form veya Source içinde ifade edilebilen her OpenAPI özelliği çalışma ortamında desteklenmeyebilir; çalıştırma öncesi hata ilgili konumu belirtir. Desteklenen veri ve doğrulama sınırları hangi tanımın çağrıya uygulanacağını açıklar.
API’ler proje bağlamında yönetilir. Bu akışta tüketici üyeliği, ücretlendirme planı veya uygulama kaydı oluşturmuyorsunuz. Bir istemcinin OAuth client ID’si gerekiyorsa kayıt kimlik sağlayıcınızda yapılır; ayrıntılar API güvenliği sayfasındadır.
OpenAPI içindeki info.version, API belgenizin sürüm etiketidir. URL’ye sürüm eklemez veya iki sürümü birlikte çalıştırmaz. Dosya biçimleri, server yolları ve çalışma sınırlarının tamamını OpenAPI destek tablosunda inceleyin.
Yetki ve kaydetme
API dosyalarını değiştirmek, Run/Reload yapmak ve Running project hedefiyle istek göndermek için platform geliştirici yetkisi gerekir. Read-only durumunda sözleşmeyi ve mevcut alanları inceleyebilirsiniz.
API editöründeki Save, sözleşmeyi ve değiştirdiğiniz erişim ayarlarını proje çalışma alanına kaydeder. Çalışan projeyi güncellemek için Run veya Reload, kalıcı deployment için Git commit ve Build gerekir. Kaydetmenin ardından hangi sürümün çağrıları karşıladığını Publication durumundan kontrol edin.