API işlemlerini ve route bağını düzenleyin

Bir operation, HTTP yöntemi ile yolun birleşimidir. GET /orders/{orderId} siparişi okurken DELETE /orders/{orderId} başka bir işlemdir. Her birinin benzersiz Operation ID değeri ve o işi yapan Direct route girişi bulunur.

İşlem ekleyin veya değiştirin

1. API design içindeki sol ağaçta Add → Operation seçin.
2. Overview sekmesinde HTTP method, Path ve Operation ID alanlarını doldurun.
3. Summary alanına kısa amacını, Description alanına kullanım koşullarını yazın.
4. İlgili Parameters, Request body ve Responses sekmelerini tamamlayın.
5. Save seçin; çalışan projede değişikliği kullanmak için Reload yapın.

Bu örnekte dışarıdan çağrılan yol /orders/preview, içeride kullanılan giriş ise direct:previewOrder değeridir. Ekrandaki Route entry açıklaması hangi Direct consumer’ı oluşturmanız gerektiğini gösterir.

Sol ağacın aramasında yöntem, path veya operation ID ile arayabilirsiniz. Aynı path altındaki yöntemler birlikte görünür. İşlem başlığındaki Delete operation simgesi onayla siler; değişikliği kaydetmek ve çalışan sürüme almak ayrı adımlardır.

Route bağlantısını kurun

getOrder işlemi şu girişe gider:

- route:
    id: order-lookup
    from:
      uri: direct:getOrder
      steps:
        - to:
            uri: direct:loadOrder

Bu parça direct:loadOrder girişli bir iş route’unuz olduğunu varsayar. Ortak iş mantığını ayrı bir Direct route’a koyup birden çok operation’dan to ile çağırabilirsiniz.

Operation ID değişirse giriş URI’sini de değiştirin. Path veya HTTP yöntemi değişirken operation ID aynı kalırsa aynı iş route’u çağrılmaya devam eder. Route dosyasının adını değiştirmek tek başına public yolu değiştirmez.

Bu etkiler düzenleme anında canlıya geçmez; Save ve ilgili Run/Reload/Build adımını tamamlayın. Projede openapi.json varsa işlemi ayrıca bağımsız bir REST consumer olarak tanımlamayın.

Bir timer veya kuyruk consumer’ı API işleminin Direct girişi yerine geçmez. Aynı Direct adresini dinleyen iki route da belirsizlik yaratır. Eksik veya birden fazla eşleşen giriş, Run/Reload ve Build sırasında hata verir. Direct, aynı proje runtime’ı içindeki çağrıdır; projeler arasında iletişim için HTTP veya mesajlaşma kullanın.

Path, query ve header parametreleri

Örnek: GET /orders/{orderId}?includeLines=true.

1. Path alanına /orders/{orderId} yazın. Yol değişkeninin parametresi otomatik oluşur; path parametresi zorunludur.
2. Parameters → Add parameter ile query veya header girdisi ekleyin.
3. Satırı açarak Name, In, Type ve Required değerlerini ayarlayın.
4. Gerekirse açıklama, örnek, enum, biçim, pattern ve sayı sınırlarını girin.
5. Daha ayrıntılı bir tanım için Parameter JSON kullanın ve Apply JSON seçin.

Path değişkenini yeniden adlandırırken Path alanını değiştirin. Aynı konum ve adla yinelenen parametreler geçersizdir. Path düzeyinde Source’ta tanımlanan bir parametre işlemlere miras kalır; işlemin aynı in ve name tanımı bunu geçersiz kılar.

Çalışan API; path/header için basit, query için form biçimindeki tekil string, integer, number ve boolean değerlerini destekler. Array/object parametreleri, cookie girdileri, parameter content, farklı serialization stilleri ve allowReserved çalışma öncesi reddedilir. Böyle bir karmaşık girdi gerekiyorsa JSON request body tasarlayın. Formda bir seçeneğin düzenlenebilmesi, çalıştırma desteği olduğu anlamına gelmez.

Parametre route’ta nasıl kullanılır?

Path/query değerleri runtime’ın mesaj header’larına aktarılır. Örneğin orderId girdisini Simple ifadesinde ${header.orderId} ile okuyabilirsiniz. Bu değeri veritabanı sorgusuna, başka bir servis isteğine veya iş kontrolüne bağlamak route’un görevidir. Query’de includeLines=true tanımlamak, route o değeri kullanmadıkça yanıta satır eklemez.

HTTP header, exchange property ve body farklı alanlardır. JSON body’sindeki customerId, kendiliğinden ${header.customerId} olmaz. Body’yi uygun JSON okuma/dönüştürme adımıyla işleyin. Girdileri hedef URL veya sorguya taşırken ilgili component’in parametreleme ve kodlama imkanlarını kullanın.

İstek gövdesini tanımlayın

1. POST, PUT, PATCH veya DELETE işlemini açın.
2. Request body → Add request body seçin.
3. Gövde zorunluysa Request body is required seçin.
4. Add media type ile örneğin application/json ekleyin.
5. Schema türünü veya ortak modelinizi seçin. Content example alanına örnek veri girin; isterseniz Use generated example ile üretilen örneği alın.
6. Kaydedip eksik, doğru ve kurala aykırı girdilerle deneyin.

Bir işlem birden çok media type bildirebilir. JSON içerikte desteklenen schema kuralları iş route’undan önce doğrulanır. application/xml gibi diğer gövdeler route’a metin olarak iletilir; XML iş kuralları ve XSD kontrolünü akışta kurun.

Request body is required, bütün gövdenin bulunmasını ister. Schema içindeki Required ise o gövdenin alanları için geçerlidir. {} göndermek “gövde göndermemek” ile aynı değildir: boş nesne, zorunlu alanları bulunmadığı için reddedilebilir. Örneği sipariş API’sinde deneyebilirsiniz.

Yanıtları tanımlayın ve üretin

Responses içinde Add response ile bir durum kodu ekleyin. Status code alanında standart kodu seçebilir veya Other… ile özel üç haneli kod, 4XX gibi aralık ya da default girebilirsiniz. Her yanıt için açıklama, media type, schema ve örnek tanımlayın. İlgili yanıtı soldaki durum sekmelerinden seçin.

Bu tanımlar istemciye ne bekleyeceğini anlatır. Durum kodunu ve gövdeyi route üretir. Örneğin başarı sonucunda 201 dönmek için:

- setHeader:
    name: CamelHttpResponseCode
    constant: 201
- setHeader:
    name: Content-Type
    constant: application/json
- setBody:
    constant: '{"orderId":"ORD-1001","status":"accepted"}'

Yanıt header’ları ve link’leri Response JSON veya Source üzerinden tanımlayın. Örneğin Location header’ını sözleşmede tanımlamanız onun değerini runtime’da üretmez; route’ta ayrıca Set Header adımı ekleyin. Yanıt schema’ları otomatik runtime doğrulamasına tabi değildir; gerçek yanıtı test ederek sözleşmeyle karşılaştırın.

Düzenleme sırasında veri kaybını önleyin

Form ve Source aynı sözleşmeyi düzenler. JSON alt alanında uygulanmamış bir değişiklik varsa Apply JSON veya Discard JSON ile tamamlayın. Üst tanımın JSON’u düzenlenirken onun alt alanları kilitlenebilir; bu, aynı parçanın iki editörden eşzamanlı değiştirilmesini engeller.

API actions → Discard son kaydedilen sözleşme ve erişim ayarlarına döner. Compare with Git çalışma alanıyla Git arasındaki farkı gösterir. Save sırasında dosya çakışması bildirilirse, ekip arkadaşınızın kaydettiği son sürümle değişikliklerinizi birleştirin.

İşlem çalışmıyorsa

• API is not runnable: Mesajda belirtilen direct: girişini, yinelenen operation ID’yi veya çakışan yolu düzeltin.
• 404: Çağrının yöntemini, proje ön ekini, servers taban yolunu ve operation path’ini birlikte kontrol edin.
• 415 / 406: Content-Type ve Accept değerlerini işlemdeki media type tanımlarıyla eşleştirin.
• 400 ve Request contract checks: Girdi alanını ve kuralı düzeltin; uygun hatalarda Open schema setting ilgili tanıma götürür.
• İş kuralı hatası: Sözleşme geçerliyse route hata yönetimini ve proje loglarını inceleyin.