İlk API'yi oluşturun

Bu örnekte GET /hello çağrısına {"message":"Hello from Lunex"} döndüren bir API hazırlayacaksınız. Sözleşme, route ve gerçek çağrı sonucunu aynı proje içinde göreceksiniz.

Hazır halini incelemek isterseniz Hello API projesini indirin ve ZIP içe alma adımlarını izleyin. ZIP’in proje kimliği help-hello-api olur; sözleşme ve route aşağıdakiyle aynıdır. İçe aldıysanız dosyaları yeniden oluşturmadan deneme adımına geçebilirsiniz.

HTTP yöntemi, endpoint veya gövde terimleri yeni geliyorsa önce REST servisi ve isteğin yolculuğunu okuyun. Bu ilk örnek sabit yanıt verir. Gönderilen veriyi işleyen, şema ve iş kurallarını gösteren devam çalışması sipariş API’si örneğidir.

Başlamadan önce

• Geliştirme ortamında düzenleyebildiğiniz bir proje açın. Örnekte proje kimliği hello-api olarak kullanılır.
• Platform geliştirici yetkiniz olsun.
• Gerçek isteği denemek için projenin geliştirme runtime’ını çalıştırabilmelisiniz. Mock için çalışan proje gerekmez.
• Dış erişim denemesi yapacaksanız ortamın gateway, adres ve kimlik doğrulama hazırlığı tamamlanmış olmalıdır. İlk örneği yalnızca Try it üzerinden çalıştırabilirsiniz.

1. Sözleşmeyi oluşturun

1. Projede Architecture sekmesine geçin.
2. OpenAPI seçin. Lunex openapi.json oluşturur ve API editörünü açar. Dosya zaten varsa API design sekmesini veya Source → Files → openapi.json yolunu kullanın.
3. General information içinde API title alanına Hello API, API version alanına 1.0.0 yazın.
4. Description alanına API’nin amacını yazın. Markdown kullanırsanız Preview ile görünümü kontrol edebilirsiniz.

Yeni sözleşme OpenAPI 3.1 ile ve /api sunucu taban yolu ile başlar. Taban yolu değiştirmek için Source içindeki servers alanını düzenleyin. Çalıştırma için bir bağıl yol kullanın; örneğin [{"url":"/api"}]. Public alan adını buraya eklemek yerine ortamın API adresini kullanın.

2. İşlemi ekleyin

1. Sol ağaçtaki Add simgesinden Operation seçin.
2. Overview sekmesinde aşağıdaki değerleri girin.

3. Responses sekmesinde 200 yanıtını seçin; yoksa Add response ile ekleyin.
4. Response description alanını doldurun. Add media type ile application/json ekleyin.
5. Schema’yı bir object olarak tanımlayıp message adlı string alanı ekleyin. Content example için {"message":"Hello from Lunex"} kullanın.
6. Save seçin. OpenAPI hatası varsa hata bağlantısından ilgili alanı düzeltin.
7. İlk denemeyi yalnızca Try it ile yapacaksanız API access → API exposure → Disabled seçip Save yapın. Böylece Run öncesinde dış adres ve erişim kaynağı hazırlamanız gerekmez. Dış erişimi yayınlama adımında ayrıca açabilirsiniz.

Alanları tek seferde hazırlamak için Source görünümüne aşağıdaki tam sözleşmeyi de yapıştırabilirsiniz:

{
  "openapi": "3.1.0",
  "info": {"title": "Hello API", "version": "1.0.0"},
  "servers": [{"url": "/api"}],
  "paths": {
    "/hello": {
      "get": {
        "operationId": "getHello",
        "summary": "Return a greeting",
        "responses": {
          "200": {
            "description": "Greeting returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["message"],
                  "properties": {"message": {"type": "string"}}
                },
                "example": {"message": "Hello from Lunex"}
              }
            }
          }
        }
      }
    }
  }
}

3. İşlemin route’unu oluşturun

1. Source → Files → Create file seçin.
2. Name alanına hello.camel.yaml yazın ve Save seçin.
3. Dosyada Code görünümünü açıp aşağıdaki içeriği yerleştirin.

- route:
    id: hello-route
    from:
      uri: direct:getHello
      steps:
        - setHeader:
            name: Content-Type
            constant: application/json
        - setBody:
            constant: '{"message":"Hello from Lunex"}'

4. Route editörünün Saved durumunu bekleyin. Route dosyaları otomatik kaydedilir; API sözleşmesinin Save işlemi ayrıdır.
5. Designer görünümüne geçin. Direct girişi, header ve body adımlarını görün. Aynı dosyayı görsel olarak da düzenleyebilirsiniz.

direct:getHello, sözleşmedeki operationId ile aynı adı taşımalıdır. Yalnızca route ID’sine getHello yazmak yeterli değildir. Her API işleminin tam olarak bir eşleşen Direct girişi olmalıdır.

4. Örnek ve gerçek yanıtı deneyin

1. API design → Paths → /hello → getHello → Try it açın.
2. Target → Mock seçip Send kullanın. Örnekteki yanıt görüntülenir; route çalışmaz ve dış sisteme istek gitmez.
3. Proje başlığından Run seçin ve çalışma durumunu bekleyin. Proje zaten çalışıyorsa dosyalar kaydedildikten sonra Reload kullanın.
4. Try it → Target → Running project seçin; gerekirse Refresh runtime status kullanın.
5. Send seçin. Beklenen sonuç HTTP 200, JSON içerik türü ve aşağıdaki gövdedir:

{"message":"Hello from Lunex"}

Mock sözleşmenizi göstermek içindir. Running project route’un gerçek davranışını çalıştırır. Erişim politikasını sınamak için ayrıca yayımlanan adresi çağırın; yayınlama adımları bu testi açıklar.

Bu örnek ekran Mock sonucunu gösterir. Geliştirme runtime’ı çalıştırılmadan sözleşmedeki örnek yanıt görüntülenmiştir; gerçek route ve erişim politikası için sonraki canlı deneme adımları gerekir.

Var olan bir API’yi içe alın

1. Sözleşmeyi JSON OpenAPI 3.0 veya 3.1 biçiminde, openapi.json adıyla hazırlayın. YAML kaynağınız varsa önce JSON’a dönüştürün.
2. Yeni veya uygun bir projede Source → Files → Upload seçin.
3. Dosyayı bırakın, Open file after saving seçili olarak Save and view kullanın.
4. Form ve Source üzerinden tanımı inceleyin. Harici $ref dosyalarını sözleşmenin içine taşıyın; tekrar kullanılacak tanımları components altında yerel referanslarla kullanın.
5. Her operation için karşılık gelen direct:<operationId> route’unu oluşturun veya mevcut route girişini uyarlayın.
6. Kaydedin; Run/Reload ile çalışma öncesi kontrolleri, Try it ile gerçek çağrıyı doğrulayın.

Projede zaten openapi.json varsa mevcut dosyayı açın ve değiştirmeden önce API actions → Compare with Git ile sürüm farkını inceleyin. Başka bir adla yüklenen JSON dosyası, projenin API sözleşmesinin yerini almaz.

Bir adım tamamlanamıyorsa

Sonraki adım: sipariş API’sini uçtan uca hazırlayın. Tek bir alanın nasıl çalıştığını arıyorsanız parametre, istek gövdesi ve hata yanıtı başvurusunu; deployment için Git akışını kullanın.