Bir satış uygulamasının sipariş bilgisini başka bir sisteme göndermesi gerektiğini düşünün. İki uygulamanın hangi adrese, hangi veriyle, hangi kimlikle başvuracağını ve sonuçta ne alacağını bilmesi gerekir. API bu iletişimin kurallarını tanımlar. Servis ise gelen isteği işleyip yanıtlayan çalışan uygulamadır.
Lunex’te API’yi tasarlarken bu kuralları OpenAPI sözleşmesine yazarsınız. Route, isteğin gerektirdiği işi yapar: veri dönüştürür, bir sistemden bilgi alır, başka bir servisi çağırır veya bir kuyruğa mesaj bırakır. API yönetimi, sözleşme ile bu çalışan davranışı ve dış erişimi birlikte düzenlemenizi sağlar.
REST, HTTP ve JSON ne anlama gelir?
HTTP, istemci ile servis arasındaki istek ve yanıt iletişimidir. REST, kaynakları adresler üzerinden sunan ve HTTP yöntemlerinin anlamından yararlanan bir tasarım yaklaşımıdır. Sipariş, müşteri veya stok gibi iş nesneleri birer kaynak olarak düşünülebilir. Her HTTP API’nin bütün REST ilkelerini uyguladığını varsaymayın; çağrının kesin kurallarını API sözleşmesi belirler.
JSON, gövdede taşınan veriyi ifade etmenin bir yoludur. REST ile aynı şey değildir; HTTP üzerinden XML veya metin de taşınabilir. Lunex JSON isteklerinin desteklenen şema kurallarını denetler. XML gövdesinin XSD kontrolü gibi işlemleri route içinde ayrıca kurarsınız.
İstemci, çağrıyı yapan uygulamadır. Endpoint, bir işlemi çağırdığınız adrestir. Aynı URL üzerindeki GET ve POST farklı işlemler olabilir. Lunex’teki operation, bu HTTP yöntemi ve yol birleşiminin sözleşmedeki tanımıdır.
Bir isteği parçalara ayırın
Aşağıdaki örnek, yayımlanmış bir sipariş okuma işlemini çağırır:
GET /orders-api/api/orders/ORD-1001?includeLines=true HTTP/1.1
Host: lunex.example.com
Accept: application/json
X-Request-Id: help-order-001| Parça | Örnekteki değer | Anlamı |
|---|---|---|
| Origin | https://lunex.example.com | Ortamın protokolü, sunucu adı ve varsa portu |
| Proje ön eki | /orders-api | İsteğin ait olduğu Lunex projesi |
| API taban yolu | /api | Sözleşmedeki servers tanımından gelen yol |
| Operation yolu | /orders/{orderId} | Çağrılabilir kaynağın sözleşmedeki adresi |
| Path değeri | ORD-1001 | Hangi siparişin istendiği |
| Query değeri | includeLines=true | Bu çağrının isteğe bağlı ayrıntısı |
| Header | Accept: application/json | İstemcinin alabileceği yanıt biçimi |
| Korelasyon header’ı | X-Request-Id | Çağrıyı ilişkilendirmek için istemcinin verdiği değer |
X-Request-Id kendiliğinden izleme Application ID alanını doldurmaz. Bu ilişkiyi akışta izleme yapılandırmasıyla kurarsınız. Path, query veya özel header tanımlamak da bu değeri iş mantığında otomatik olarak kullanmaz; route’un ilgili girdiyi okuması gerekir.
Gövde gönderen bir çağrı şu şekilde olabilir:
POST /orders-api/api/orders/preview HTTP/1.1
Host: lunex.example.com
Content-Type: application/json
Accept: application/json
{"customerId":"C-100","quantity":2}Content-Type, gönderdiğiniz gövdenin biçimidir. Accept, almak istediğiniz yanıtın biçimidir. Bunlar aynı değeri taşımak zorunda değildir. JSON metni gönderirken Content-Type yanlışsa, veri görünüşte doğru olsa bile servis isteği reddedebilir.
HTTP yöntemini işinize göre seçin
- GET, kaynağı veya listeyi okur. Kaydı değiştiren bir iş için kullanmayın; Lunex API runtime’ında request body tanımlamayın.
- POST, kayıt oluşturma veya veri üzerinde bir işlem isteme için kullanılır. Aynı istek iki kez gönderilirse iş iki kez yapılabilir.
- PUT, belirli kaynağın durumunu gönderilen temsil ile belirler. Aynı isteğin tekrarında aynı hedef durumu sağlayacak iş davranışını tasarlayın.
- PATCH, kaynağın bazı alanlarını değiştirir. Hangi alanların nasıl güncelleneceğini sözleşmede açıklayın.
- DELETE, kaynağı siler. Tekrar çağrının iş etkisini ve dönecek durumu belirleyin.
Bir yöntem seçmek ilgili veritabanı işlemini oluşturmaz. Örneğin DELETE /orders/{orderId} tanımlamak, siparişi gerçekten silen route olmadan işi tamamlamaz. HTTP yöntemlerinin anlamı için HTTP Semantics başvurusuna bakabilirsiniz.
Lunex içinde istek hangi yolu izler?
- İstemci, ortamın yayımlanan işlem adresine başvurur. Bu adresi API access → Copy operation address üzerinden alın.
- Dış erişim katmanı, seçili Basic, API key veya JWT politikasını uygular. Gerekli kimlik veya izin sağlanmıyorsa iş route’u çağrılmaz.
- Çalışan API, yöntemi ve yolu sözleşmedeki operation ile eşleştirir. Gerekli girdileri, içerik türünü ve desteklenen istek şeması kurallarını kontrol eder.
- Operation ID, aynı runtime içindeki
direct:<operationId>girişini belirler. ÖrneğinpreviewOrder,direct:previewOrderroute’unu çağırır. - Route, iş mantığını çalıştırır. Burada bir bağlantı kullanılıyorsa ilgili dış sistemde de işlem gerçekleşebilir.
- Yanıt, route’un ürettiği durum kodu, header’lar ve gövdeyle istemciye döner. Sözleşmedeki response örneği gerçek yanıta otomatik olarak kopyalanmaz.
Try it → Running project, geliştirme runtime’ına doğrudan test isteği gönderir; dış erişim politikasını sınamaz. Mock ise tarayıcıda örnek yanıt üretir ve bu işleme zincirini çalıştırmaz.
Servis sunmak ile servis çağırmak
Bir operation ve ona bağlı Direct girişi oluşturarak gelen çağrıyı karşılarsınız. Route içine HTTP bağlantısı ekleyerek başka bir servisi çağırırsınız. Bir sipariş API’si gelen isteği alıp stok servisini çağırabilir; aynı akışta hem servis sunan hem istemci rolü bulunur.
İki tarafın kimlik bilgileri bağımsızdır. Sizin API’nize erişen istemcinin JWT’si, stok servisine kendiliğinden erişim sağlamaz. Dış sistemin bağlantısını ve credential’ını bağlantı ve Secret ayarlarında ayrıca hazırlayın.
direct: aynı proje runtime’ındaki senkron çağrı adresidir; dışarıdan çağrılabilen bir URL veya kalıcı kuyruk değildir. İki proje arasında HTTP ya da mesajlaşma bağlantısı kullanın.
REST tanımı ile OpenAPI’nin ilişkisi
OpenAPI kullanan projede HTTP işlemlerinin kaynağı openapi.json dosyasıdır. Bu dosyada yöntemleri ve yolları, route dosyalarında ise direct:<operationId> girişlerini tanımlayın. Aynı projeye ayrıca bağımsız REST consumer eklemek çalıştırma öncesinde reddedilir.
Native REST DSL’nin model ve editörleri başka akışlar için mevcut olsa da, OpenAPI projesinde ikinci bir HTTP işlem listesi oluşturmayın. Route ID, dosya adı veya Architecture üzerindeki görünüm, sözleşmedeki operation’ın yerine geçmez.
Yanıt size ne söyler?
Örneğin 200 ve bir JSON gövdesi, çağrının başarılı işlendiğini anlatır. 201, kaynak oluşturulduğunu; 202, işin kabul edildiğini fakat henüz tamamlanmamış olabileceğini anlatır. Kuyruğa bırakılan işte 202 almak, hedef sistemde işlemin tamamlandığını kanıtlamaz.
4xx sonucunda girdiyi, adresi veya erişim koşullarını; 5xx sonucunda iş akışını ve bağlı servisleri inceleyin. Durum kodunu gövde ve hata konumuyla birlikte okuyun. Hata teşhisi hangi kontrolün nerede yapılacağını gösterir.
Bir değişiklik ne zaman etkili olur?
Editörde yazdığınız tanım önce taslaktır. Save proje dosyasını günceller. Kaydedilen değişikliğin geliştirme runtime’ına geçmesi için Run/Reload, kalıcı deployment’a geçmesi için Commit and push → Build gerekir.
İstemcilerin çağırdığı ortak adresin hangi runtime’a yönlendiğini Publication → Serving ile kontrol edin. Test ve yayınlama sayfası bu geçişleri ayrıntılı anlatır. Uygulamaya geçmek için ilk API’nizi, gövdeli bir çağrı için sipariş örneğini izleyin.