Xpoda Api Service özelliği V4.0 ve sonrasında kullanılabilir. Studio girişi yapıldıktan sonra Api Service alanından api koleksiyonu oluşturulur.
V4.0 ile Body API Collections hizmete girecektir. V4.1 versiyonuyla birlikte diğer API Collections hizmete girilmesi planlanmaktadır ve yayımlanan yeni versiyon notlarında detaylar paylaşılacaktır. Eş zamanlı yeni eklenen API Collections dokümana dahil edilecektir.
1.Create a new API Collection; Bu alandan API koleksiyonlarına ait API modülleri oluşturulur. Create a new API Collection üzerine gelinir ve seçilir. Sonrasında New API Collection başlığıyla görünen pop-up ekranı açılır.
2.New API Collection; 3 çeşit API Collection oluşturma yöntemi vardır. Yukarıda paylaşılan görselde de kırmızı işaretlenmiş alanda da görüldüğü gibi; Bu yöntemlerden 2’si Import Options seçeneğiyle oluşturulabilir. Bu 2 seçeneği kullanmadan Create and Go butonuna basarak API Collection manuelde oluşturulabilmektedir.
2.1.Enter a title for your collection; Oluşturulan API Collection kartına bu alandan isim verilir. Boş geçilemez alandır. Oluşturulan API Collection yöntemlerine isim verilmesi gerekmektedir.
2.2.Import from Swagger/OpenAPI; Bu metoda ait API URL bu alana yazılır. URL yazıldıktan sonra Create and Go butonuna basılır. Açılan pop-up ekranında URL içindeki Request to Import bilgileri gösterilir. Kullanılacak Request to Import seçimi yapılır. Import Selected butonuna basılır. Birden fazla Request to Import seçildiğinde her bir metoda ait API Request istemini sistem oluşturur.
2.3.Import from Postman; Bu metoda ait postman API dosyası seçilir ve sonrasında Create and Go butonuna basılır. (Aşağıda paylaşılan sol taraftaki görsel). Açılan pop-up ekranında API istemi içindeki metod bilgileri gösterilir. (Aşağıda paylaşılan sağ taraftaki görsel). Kullanılacak Request to Import seçimi yapılır. Import Selected butonuna basılır. Birden fazla Request to Import seçildiğinde her bir metoda ait API Request istemini sistem oluşturur. (Aşağıda paylaşılan sağ taraftaki görselde 2 tane Request to Import seçilmiştir).
Not: API Request istemini sistem oluştururken herhangi bir işlem yapmadan birkaç saniye beklenmesi gerekmektedir. API Request kartları oluştuğunda ekranda gösterilecektir. (Aşağıda paylaşılan 2.görsel).
Örnek olarak Mikronun Json API istemi aşağıda ekran görselleriyle paylaşılmıştır.
3.Create new API Request; New API Collection aşamasının sonunda oluşan API istemleri burada gösterilir.
Yukarıda paylaşılan ekran görselindeki gibi API Request istemi oluşup ekrana geldikten sonra düzenleme butonuyla (Yukarıda paylaşılan görselin sağ üst köşesinde kalem ikonu olan düzenleme butonları).
Açılan pop-up ekranından API Request istemine ait bilgilere ulaşılabilir (Yukarıda paylaşılan ekran görseli). İstenirse bilgiler güncellenebilir veya istem silinebilir.
Not: API Request istemi oluşturulduktan sonra görsel kontrol yapılması tavsiye edilir.
Oluşan API Request istemleri üzerine gelinerek seçim yapılır ve Request Details ve Authentication detaylarına gidilir. (Örnek API Request; Mikro Cari API Service>Cari Kaydet V2 Save - Mikro Cari API Service>Cari Güncelle V2 Upload istemleri üzerine gelinerek seçim yapılır).
Dokümanın devamında Manuel API Collection oluşturma bölümünde Request Details ve Authentication detaylarının gösterildiği bölümle alakalı daha detaylı anlatım yapılmıştır.
4. Manuel API Collection Oluşturma; Bu alanın üzerine gelinip seçimi yapıldıktan sonra manuel API Collection oluşturulurken;
4.1.Create a new API Collection; Create a new API Collection üzerine mouse imleci getirilir ve seçilir. Açılan New API Collection pop-up ekranında; Enter a title for your collection alanından oluşturulan API Collection kartına bir isim verilir ve Create and Go butonuna basılır.
4.2. API Collections; Oluşan API Collections’ın isiminde değişiklik yapılabilir veya silinebilir. (Yukarıda paylaşılan ekran görselinin sağ üst köşesinde kalem ikonuyla görünen butonları kullanılarak). Sonrasında oluşan API Collections’a ait API Request tanımlarını yapmak için mouse collections üzerine getirilir ve seçimi yapılır. (Örnek görselde Cari Kart API Koleksiyonu seçilmelidir).
4.3.Create new API Request; Açılan ekrandan Create new API request üzerine mouse getirilip seçilir.
Sonra açılan pop-up ekranından API istemine ait bilgiler girilir. (Yukarıda paylaşılan 2.ekran görseli).
4.3.1.Request Title; Bu alanda kaydı oluşturulan API istemine ait isim bilgisi olmalıdır.
4.3.2.Service Url; Bu alanda kaydı oluşturulan API istemine ait service url bilgisi olmalıdır.
4.3.3.Method; Bu alanda kaydı oluşturulan API isteminin metodu seçilir. Get, Post, Put, Delete, Parth, Head ve Options metod türlerinden seçim yapılır.
4.3.4.Service Auth Type; Bu alanda kaydı oluşturulan API isteminin varsa service auth type bilgisi olmalıdır.
4.3.5.Authentication Url; Bu alanda kaydı oluşturulan API isteminin varsa authentication Url bilgisi olmalıdır.
4.6.6.Authentication Type; Bu alanda kaydı oluşturulan API isteminin varsa authentication type bilgisi olmalıdır.
4.3.7.Datasource; Bu alanda kaydı oluşturulan API isteminin data source bilgisi olmalıdır. Params, Form-Encoded ve Form Data Value parametre tiplerinde datasource kullanılabilir. DataSource’tan dönen sonuç kadar api’nin tetiklenmesi sağlanır.
İlgili API Request bilgileri girildikten sonra Save butonuyla bilgiler Kaydedilir.
Kaydedilen API Request istemi request title alanında yazılan ismiyle ekrana gelir. İstem içinde değişiklik yapılmak istendiğinde düzenleme butonuyla API Request ekranına tekrar ulaşılabilir. (Yukarıda paylaşılan ekranda kırmızı işaretli kalem ikonu olan butonla).
Kaydedilen API Request istemi üzerine mouse getirilir ve seçilir. (Örnek API Request istemi; Demo API Cari Save).
4.4.Requeat Detail and Authentication; Aşağıda paylaşılan ekran görselindeki gibi açılan ekrandan API Request’in Request Details ve Authentication alanları kullanılarak parametreleri tanımlanır.
Aşağıda kolon açıklamaları genel açıklamalarıdır. Her bir Type’a göre parametre tanımları değişkenlik göstereceğinden dokümanın devamında örnekleriyle açıklamaları yapılmıştır.
Request Details alanından API isteminin parametrelerini, hemen altındaki Authentication alanından da kullanılacak Kimlik Doğrulaması bilgilerinin girişleri yapılır. Artı butonuyla giriş satırı aktifleştirilir. Açılır kutular dışındaki alanlar kullanılacaksa bilgileri yazıldıktan sonra klavyeden Enter yapıldıktan sonra satırın bilgisi kaydedilmiş olur. Bilgi yazıldıktan sonra hücredeki bilginin altında kırmızı vurgulama varsa kayıt yapılamamıştır, klavyeden enter kullanılarak kayıt atılır ve kırmızı vurgunun kaybolduğu ilgili hücrede kontrol edilir. Aktif satırın en sağında bulunan Sil butonuyla da kaydı olan parametre satırı silinebilir.
4.4.1.1.ID; Request Detail satırlarının kayıt ID bilgisinin olduğu yerdir. Satır kaydedildikten sonra ID bilgisi burada görünür. Sistemin otomatik ürettiği bir numaradır. Create edilen satırdayken bir kere klavyeden enter yapılırsa ID oluşur ve alanında gösterilir.
4.4.1.2.TYPE; Kullanılan api tipinin, create edilen Request Detail satırındaki type tanımı bu alandan yapılır. Boş geçilemez alandır. Body, Params, Form-Encoded, Form Data, XML, GraphQL ve Header api tip seçeneklerinden seçim yapılır.
4.4.1.3.PARAMETERNAME; Kullanılan api içindeki alan isimleri, create edilen Request Detail satırında parametername alanında tanımlanır. Boş geçilemez alandır.
4.4.1.4.DESCRIPTION; Create edilen Request Detail satırında açıklama tanımı yapılacaksa bu alan kullanılır.
4.4.1.5.VALUE; Create edilen Request Detail satırında sabit değer tanımlanmak istenirse bu alana değer yazılır.
4.4.1.6.VALUETYPE; Kullanılan api içindeki alanların valuetype bilgilerine bağlı olarak, create edilen Request Detail satırının valuetype seçiminde ilgili valuetype’ı seçilir. String, Integer, boolean, float, decimal, object ve array valuetype’ları seçilebilir.
Boş geçilemez alandır.
4.4.1.7.PARENTID; Request Detail satırının bağlı olduğu ID bilgisi buraya yazılır. Her Request Detail satırı içinde bulunduğu ID ye bağlanır.
4.4.1.8.CHILDDATASOURCE; Array’in altındaki objeye bağlı field’lerin data listesinin oluşturulduğu alandır.
4.4.2.Authentication; Create edilen API Request için kullanılacak Kimlik Doğrulaması bilgilerinin girişleri bu alandan yapılır.
5.Request Details TYPE çeşitleri: Örnek anlatımla dokümanın devamında V4.0 ile birlikte kullanılabilecek Body ve Params type’ların detayları paylaşılmıştır.
5.1.Body Type; Json API istem tipidir. Json API istemi kullanımında TYPE seçimi olarak Body seçilmelidir. Örnek olarak manuel tanımlama yöntemiyle aşağıda detaylarının görülebileceği Create new API request’i tanımladık.
5.1.1. Create new API request; Tanımlama işlemleri tamamlandıktan sonra Save butonuyla Create new API request kartı kaydedilir.
Kaydı yapılan Service kartının üzerine mouse getirilir ve seçilir. (Yukarıda paylaşılan görselde Demo API Cari Save ismiyle kaydedilen service kartını görebilirsiniz).
5.1.2.Request Details; Açılan ekranda Request Detail ve Authentication detayları girilir ve buradan API isteminin Parametre tanımları yapılır. Aşağıdaki görselde örnek Json API isteminin parametre tanımlarına ait görsel paylaşılmıştır.
5.1.3.Authentication; Kullanılan Json örneğinde Authentication detayı olmadığı için kullanılmamıştır.
Artı butonuyla Authentication girişi yapılır. Açılır kutular dışındaki alanlara bilgiler yazıldıktan sonra klavyeden Enter yapıldığında girilen bilgi kaydedilmiş olur. Sil butonuyla da kaydı olan parametre satırı silinebilir.
5.1.2.1.ID; API servis doğrulama detay satırının kayıt ID bilgisinin olduğu yerdir. Satır kaydedildikten sonra ID bilgisi burada görünür.
5.1.2.2.TYPE; Json API Collections örneği kullanılmıştır, dolayısıyla Body type seçilmiştir.
5.1.2.3.PARAMETERNAME; Json API Collection içindeki alanların isimleriyle birebir, create edilen API Request Detail parametername satırlarının isimleri bu alana yazılmıştır.
5.1.2.4.DESCRIPTION; Create edilen Request Detail satırında açıklama tanımı yapılacaksa bu alan kullanılır.
5.1.2.5.VALUE; Create edilen Request Detail içinde sabit değer kullanılmadığı için bu alana değer yazılmamıştır.
5.1.2.6.VALUETYPE; API Request Detail alanların alan tipleri bu alandan seçilir. String, Integer, boolean, float, decimal, object ve array valuetype’ları seçilebilir.
5.1.2.7.PARENTID; Create edilen Request Detail satırının bağlı olduğu ID bilgisi buraya yazılır.
5.1.2.8.CHILDDATASOURCE; Post edilecek Json data içerisindeki liste elemanının childdatasource kullanımı aşağıdaki ekran görselinde gösterilmiştir.
Görselde Json Datanın Bilgileri sağ tarafta ve create edilen Xpoda Request Detail parametre bilgileri sol taraftadır. Ekran görseline dikkat edilirse; create edilen Xpoda Request Detail satırları Json Datanın kod sırasına denk gelecek uygulanmıştır.
TYPE; Örnekte Json API istem tipi kullanıldığı için Type Body seçilmiştir.
PARAMETERNAME; Json datadan gelen alan isimleri buraya yazılır. Örnek görselde Json Datadaki alan isimleriyle parametername alanında birebir yazılmıştır.
VALUETYPE; Json datadan gelen alanların ValueType’larına göre Request Detail satırları oluşturulur. Örnek görselde Json Datadaki alanların ValueType’larıyla birebir yazılmıştır.
PARENTID; Create edilen Request Detail satırının bağlı olduğu ID bilgisi bu alanda tanımlanarak eşleştirilmiştir.
CHILDDATASOURCE; Parametre tanımları içinde Array kullanılıyorsa datasource sql sorgusu kullanılması gerekmektedir.
Yukarıda paylaşılan görsel içinde örnek Json API Collection’a ait create edilen Object ve Array Request Detail satırlarına ait uygulama detayları şöyledir;
- Array; Json örneğinde köşeli parantezi olan alanların Request Detail parametre tanımı Array’dir. Parametre tanımları içinde Array kullanılıyorsa datasource sql sorgusu kullanılması gerekmektedir. CHILDDATASOURCE içine yazılan Sql sorgusundan gelen kolon isimleriyle, array’a bağlı olan parametre satırlarının PARAMETERNAME içinde yazılan isimleriyle aynı olmak zorundadır. Kullandığınız Sql sorgusunda $PRecordID parametresi eklenmiştir. Bu parametrenin ne işe yaradığı bu api’nin tetiklendiği aşamada anlatılmıştır.
Json örneğinde köşeli parantezi olan alanların Request Detail parametre tanımı VALUETYPE Array’dir. Json Data Bilgileri görselinde köşeli parantezden sonraki alanlarda; İsimleri PARAMETERNAME de birebir yazılır, VALUETYPE açılır kutusundan ilgili alan tipi seçilir. CHILDDATASOURCE içine yazılan Sql sorgusundan gelen kolon isimleriyle, array’a bağlı olan parametre satırlarının PARAMETERNAME içinde yazılan isimleriyle aynı olmak zorundadır.
- Örnek Json datanın metodunda "cariler": [ / "adres": [ / "yetkili": [ gibi köşeli parantez içinde metod alanları varsa burada Type=Body ve ValueType=array seçilmiş olmalıdır.
- Array olarak kayıtlı parametre satır kaydından sonra ([köşeli parantez satırı), Json API isteminde süslü parantez ( { ) ile sorgu devam ediyorsa Object request details parametre satırı açılmalı ve burada da Type=Body ve ValueType=Object seçilmiş olmalıdır. Object satırının ParentID kısmına ilgili Array parametre satırının ID nosu yazılır.
Json API örneğinde; "cariler": [
{……. örneğindeki gibi köşeli parantez (array valuetype) sonrasında süslü parantez (object valuetype) kullanıldığı için hemen sonrasında object request details satırı oluşturlmuş ve süslü parantezde (object valuetype) isim olmadığı için ParameterName alanı boş geçilmelidir.
- Object; Json örneğinde süslü parantezi olan alanların Request Detail parametre tanımı Object’tir.
Json örneğinde süslü parantezi olan alanların Request Detail parametre tanımı VALUETYPE Object’tir. Json Data Bilgileri görselinde süslü parantezden sonraki alanlarda; İsimleri PARAMETERNAME de birebir yazılır, sabit değer gönderilecekse VALUE içine yazılır, VALUETYPE açılır kutusundan ilgili alan tipi seçilir. Süslü parantezden sonraki alanların PARENTID’si object parametre satırının ID’sidir.
- Örnek Json datanın metodunda "Mikro": { örneğindeki gibi süslü parantez (object) içinde metod alanları varsa burada Type=Body ve ValueType=Object seçilmiş olmalıdır.
- Object olarak kaydedilen satırın içinde barındırdığı alanların request details girişlerinde PARENTID değerleri, ilgili Object satır ID nosudur.
Örnek Json datanın metodunda "Mikro": { süslü parantezi içinde olan ve request details parametre girişi olan cari_kod, cari_unvan1, cari_vdaire_no, cari_vdaire_adi satırlarının PARENTID kısmında Mikro (object) satırına ait ID yazılmıştır.
Diğer ValueType seçenekleri Json API metodundaki alan tiplerine göre kullanılmalıdır. Object ve Array dışında kalan parametreler value tiplerine göre seçilir. (Örn; String, İnteger, boolean, float, decimal).
- String; Metin verilerini saklamak için kullanılır. Örneğin, isimler, açıklamalar veya herhangi bir metinsel veri için kullanılır. Örnek Json API datası içinde string olan alanlar için valuetype seçimi string’tir.
- Integer; Tam sayı değerini temsil eder. Ondalık kesir içermez ve negatif, sıfır veya pozitif sayılar olabilir. Örnek Json API datası içinde Integer olan alanlar için valuetype seçimi Integer’tir.
- Boolean; Sadece iki değeri alabilen bir veri tipidir: true (doğru) veya false (yanlış). Genellikle koşul ifadelerinde, mantıksal işlemlerde kullanılır. Örnek Json API datası içinde Boolean olan alanlar için valuetype seçimi Boolean’tir.
- Float; Ondalık sayılar için kullanılan veri tipidir. Genellikle daha düşük hassasiyetli sayılar için kullanılır. Örnek Json API datası içinde Float olan alanlar için valuetype seçimi Float’tır.
- Decimal; Yüksek hassasiyet gerektiren ondalıklı sayılar için kullanılır. Genellikle finansal hesaplamalar gibi hassasiyetin önemli olduğu durumlarda tercih edilir. Örnek Json API datası içinde Decimal olan alanlar için valuetype seçimi Decimal’dir.
6. Api Service Xpoda Aksiyon Kullanımı; API Collection modülümüz oluşturulduktan sonra, studio’da api service kullanımını sağlatan aksiyonun oluşturulması gerekmektedir.
Aksiyon senaryomuzu form içindeki buton komponentinde oluşturalım;
Geliştirme tuvalindeki Buton seçildikten sonra özellikler bölümünde aksiyon butonu seçilir. (Yukarıda paylaşılan yeşil renkli buton). Add New Action seçildikten sonra;
6.1.Type of action; Komponente ait aksiyon tipleri görülür. Örneğimiz buton olduğu için When clicked seçilmiştir.
6.2.Operation; Seçilen aksiyonun nasıl işlem yapacağı belirlenir. Örneğimiz için Update Value seçilmiştir. Formumuz içindeki listeye api service çalıştıktan sonra dönen sonuçlar gösterilmiştir.
6.3.Description; Aksiyona açıklama eklenmek istendiğinde bu alan kullanılır. Bu alana yazılan bilgi aksiyon kaydedildikten sonra aksiyon kutucuğu içinde gösterilir. (Yukarıda paylaşılan ekran görselindeki gibi).
6.4.Heading; Aksiyona başlık eklenmek istendiğinde bu alan kullanılır.
6.5.Parameter Query; Yukarıda paylaşılan ekran görselinde kırmızı işaretlenmiş alanda ki açılır kutudan api service kullanımı için Api Engine seçilir.
Bu alana yazılacak sql sorgusu POST edilecek bilgi içermelidir. Aksiyonda Api Engine içindeki sql sorgusu içinde dönen bilgiye RecordId alias'ı verilir, aşağıdaki görselde görüldüğü gibi api service request detail tanımlarının yapıldığı array satırında childdatasource içinde kullanılır. Sistem bu sayede aksiyon içinden aldığı bilgiyi replace ederek servisi çalıştırır.
Yukarıda paylaşılan ekran görselinde görünen XPD_CARI_POST formundan mikro cari hesaplar tablosuna yeni cari kart kaydı atılarak cari kart oluşturulmuştur.
6.6.Api Collection; Aksiyonda kullanılacak kayıtlı api collection seçilir.
6.7.Api Request; Aksiyonda kullanılacak kayıtlı api collection içindeki request’lerden seçim yapılır.
6.8.Data Query; Yukarıda paylaşılan ekran görselinde turuncu işaretlenmiş alana yazılacak sql sorgusu GET edilecek bilgileri içermelidir.
Api service çalıştığında sistem otomatik geçici tablolar oluşturur. Tablo isimlerinin başında # işareti olan tablolar sistemin oluşturduğu işlem sırasında oluşan geçici tablolardır. Service çalıştığında servis sonucuna göre sistem ihtiyaç kadar geçici tabloları oluşturur. Bu tablolar #XPODA_API_TABLE_X ismiyle oluşur.
Api service çalıştıktan sonra sistem bu bilgileri XPODA_API_REQUEST_LOGS tablosunda request ve response bilgilerini ve XPODA_ERROR_LOGS tablosunda da oluşan hata bilgilerini tutmaktadır. Aşağıda paylaşılan görselde başarılı post edilen cari kart örneğine ait XPODA_API_REQUEST_LOGS tablosundaki kayıt örneği paylaşılmıştır.
6.9.No Logging; Yes seçimi yapıldığında XPODA_API_REQUEST_LOGS tablosuna kayıt atılmaz
6.10.Run Condition; Aksiyona çalışma koşulu eklenmek istenirse sql sorgusu bu alana yazılır. Buraya yazılan koşula bağlı şekilde aksiyon çalıştırılmış olur. Dönen sonuç 1 ise run condition çalışır.
6.11. Request Information / Confirm Message; Aksiyon çalışmadan önce client ekranında onay alınmak istenirse Request Information Yes seçilir. Sonrasında Confirm Message içine gösterilecek mesaj içeriği yazılır. Genel kullanımı client ekranında yanlışla butona basılmalardan kaynaklı hatalı işlem yapılması engellenmektir.
Studio görünümü;
Client görünümü;