Web API Dokümanı

Giriş

Bu doküman, üçüncü parti uygulamalarınızın Marksoft verilerine güvenli erişim sağlaması amacıyla geliştirilen Web Uygulama Programlama Arayüzü (API) hizmetinin kullanımını kapsamaktadır. Tüm istekler, HTTP protokolü aracılığıyla JSON formatında iletilir ve alınır. Güvenlik amacıyla, her istek kimlik doğrulaması gerektirir.

Temel URL

API'nin varsayılan temel adresi aşağıdaki gibidir:

http://localhost:8080

Kimlik Doğrulama

API, Basic Authentication yöntemi ile korunmaktadır. Korumalı endpoint'lere yapılan her istekte Authorization başlığının (header) gönderilmesi zorunludur.

Bu başlık, Basic ön eki ile birlikte Base64 formatında kodlanmış Marksoft Kullanıcı Adı ve Şifre bilgisini içermelidir.

Örnek:

Kullanıcı adı admin ve şifre 12345 ise, birleştirilmiş string admin:12345 olur. Bu string'in Base64 karşılığı YWRtaW46MTIzNDU= şeklindedir.

HTTP isteği başlığı (header) şöyle olmalıdır:

Authorization: Basic YWRtaW46MTIzNDU=

Endpoints

API iki ana endpoint sunmaktadır. Tüm endpoint'ler POST metodu ile çalışır.

var settings = {
  "url": "http://localhost:8080/gettables",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Authorization": "Basic YWRtaW46MTIzNDU="
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

{
    "success": true,
    "tables": [
        {
            "table": "viewfirmalar",
            "description": "Firmalar",
            "columns": {
                "id": "int",
                "firmano": "varchar",
                "firmaunvani": "varchar",
                "...": "..."
            }
        },
        ...
        {
            "table": "viewlogs",
            "description": "Sistem Kayıtları",
            "columns": {
                "id": "int",
                "uniqueid": "varchar",
                "...": "..."
            }
        }
    ]
}

{
    "success": false,
    "message": "Yetkisiz İşlem !"
}

var settings = {
  "url": "http://localhost:8080/getdata",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Authorization": "Basic YWRtaW46MTIzNDU=",
    "Content-Type": "application/json"
  },
  "data": JSON.stringify({
    "table": "viewmarkalarim",
    "select": ["*"],
    "where": {
      "conditions": [
        {
          "column": "haksahibiil",
          "operator": "=",
          "value": "ANKARA",
          "logical": "AND"
        },
        {
          "column": "haksahibiilce",
          "operator": "=",
          "value": "YENİMAHALLE",
          "logical": "AND"
        }
      ],
      "combine": "AND"
    },
    "groupby": ["basvuruno"],
    "orderBy": [{"column": "kayittarihi", "direction": "DESC"}],
    "limit": 10
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

{
    "success": true,
    "totalcount": 150,
    "page": 1,
    "pageSize": 2,
    "data": [
        {
            "id": 1,
            "basvuruno": "2024/071525",
            "...": "..."
        },
        {
            "id": 2,
            "basvuruno": "2024/181274",
            "...": "..."
        }
        ...
    ]
}

{
    "success": false,
    "message": "Yetkisiz İşlem !"
}

Sorgu Yapısı (JSON)

/getdata endpoint'ine gönderilecek JSON gövdesi, SQL sorgusuna benzer bir yapıya sahiptir. Aşağıda bu yapının alanları ve açıklamaları verilmiştir.

where Nesnesinin Yapısı

where nesnesi, koşulları tanımlayan bir conditions dizisi içerir.

Sorgu yapısının C# ile yazılmış class nesnesi aşağıdaki şekildedir.

public class QueryRequest
{
    public string table { get; set; }
    public List<string>select { get; set; }
    public Where where { get; set; }
    public class Where
    {
        public List<Condition> conditions { get; set; }
        public class Condition
        {
            public string column { get; set; }
            public string @operator { get; set; }
            public object value { get; set; }
            public string logical { get; set; }
        }
        public string combine { get; set; }
    }
    public List<string> groupBy { get; set; }
    public List<OrderBy> orderBy { get; set; }
    public class OrderBy
    {
        public string column { get; set; }
        public string direction { get; set; }
    }
    public int limit { get; set; }
    public int offset { get; set; }
}

Örnek Sorgular

/getdata endpoint'i için hazırlanmış bazı örnek JSON sorguları aşağıdadır.

1. Tüm Firmaları Getirme (İlk 10 Kayıt)

viewfirmalar tablosundaki tüm sütunları seçer ve ilk 10 kaydı getirir.

{
    "table": "viewfirmalar",
    "limit": 10
}

2. Belirli Bir İldeki Firmaları Filtreleme

il sütunu "Ankara" olan firmaları, firma unvanına göre alfabetik olarak sıralayarak getirir.

{
    "table": "viewfirmalar",
    "select": ["id", "firmaunvani", "il", "ilce"],
    "where": {
        "conditions": [
            {
                "column": "il",
                "operator": "=",
                "value": "ANKARA"
            }
        ]
    },
    "orderBy": [
        {
            "column": "firmaunvani",
            "direction": "ASC"
        }
    ]
}

3. Birden Fazla Koşul Kullanma (AND)

viewfirmalar tablosunda, belirli bir şehre (il='ANKARA') ve ilçeye (ilce='YENİMAHALLE') ait firmaları getirir.

{
    "table": "viewfirmalar",
    "where": {
        "conditions": [
            {
                "column": "il",
                "operator": "=",
                "value": "ANKARA"
            },
            {
                "column": "ilce",
                "operator": "=",
                "value": "YENİMAHALLE"
            }
        ]
    }
}

4. LIKE Operatörü ile Arama

Firma unvanı içinde "teknoloji" kelimesi geçen firmaları arar.

{
    "table": "viewfirmalar",
    "where": {
        "conditions": [
            {
                "column": "firmaunvani",
                "operator": "LIKE",
                "value": "%teknoloji%"
            }
        ]
    }
}

5. IN Operatörü ile Çoklu Değer Filtreleme

id değeri 101, 105 veya 210 olan firmaları getirir.

{
    "table": "viewfirmalar",
    "where": {
        "conditions": [
            {
                "column": "id",
                "operator": "IN",
                "value": [101, 105, 210]
            }
        ]
    }
}

Hata Mesajları

Hatalı gönderim yapıldığında, success değeri false olarak döner ve message parametresinde hatanın açıklaması yer alır.

Hata Açıklamaları

• Yetkisiz İşlem !: Basic Auth geçersiz.
• Geçersiz Content-Type !: Content-Type başlığı application/json değil.
• Geçersiz Body !: Gönderilen JSON hatalı veya boş.
• Geçersiz JSON Verisi !: JSON istenilen formatta değil.
• Bu Tabloya Erişilemez !: İzin verilmeyen tablo sorgulandı.
• Geçersiz Sorgu !: Sunucu sorguyu işleyemedi.
• Bu işlem POST method gerektirir.: GET veya başka metod ile istek yapıldı.