Giriş

Switch API, veri servislerinin ve Switch DB plaftormunun birincil dağıtım noktasıdır. Bu düşük seviyeli HTTP bazlı API ile query tabanlı işlemler gerçekleştirerek veritabanınıza veri ekleme, düzenleme, silme ve listeleme işlemlerini sağlayabilirsiniz.

API'ı çağırmak için geliştirici portalı üzerinden alacağınız veritabanı sunucusuna, API Key ve API Secret parametrelerine ihtiyacınız bulunmaktadır.


API'ı çağırmak için kullanılan URL formatı:

GET /

https://{{API_LOCATION}}.switchapi.com/


Tüm sunucularımız uluslararası standartlarda ve en az n+1 yedekli şekilde çalışan veri merkezlerinde barınmaktadır. İstanbul sunucularımız Radore, İzmir sunucularımız Netdirekt, Frankfurt sunucularımız Amazon Web Services ve IBM Cloud SoftLayer, California sunucularımız Microsoft Azure'da çalışmaktadır.

API Kullanımı

API'da herhangi bir istek yapabilmek için Access Token parametresine ihtiyacınız bulunmaktadır. Access Token parametresini üretmek için /Token noktasını kullanabilirsiniz.


GET /Token

Access Token üretmek için geliştirici portalı üzerinden alacağınız API Key ve API Secret parametrelerine ihtiyacınız bulunmaktadır. Request'te header üzerinden gönderilecek olan API Key parametresi portaldaki API Key, Signature parametresi md5(APISecret+ExpireTimestamp) şeklinde üretilir. Expire parametresinde token'ın expire olacağı tarih ve saat bilgisi ISO 8601 standartlarına uygun olmak kaydıyla milisaniye bilgisi eklenmiş haliyle Unix Time formatında olmalıdır.

Headers:
APIKey: {{API_KEY}}
Signature: {{SIGNATURE}}
Expire: {{EXPIRE}}
                        

API Hata Mesajları

API'da standart hata mesaj formatı mevcuttur. Standart bir hata mesajı aşağıdaki formatta yanıt verecektir.

{
    "ResponseTime": "2016-09-15T04:00:24.4749654+03:00",
    "Response": "ServiceException",
    "ErrorMessage": "Value cannot be null. Parameter name: 'AccessToken'."
}
                        

Bu hatalara dair response başlıkları aşağıdaki gibidir:

HTTP 401 - Unauthorized: Verilen AccessToken parametresinin geçersiz olduğunu bildirir.
HTTP 403 - SecurityException: Güvenli olmayan bir istek yapıldığını bildirir.
HTTP 404 - MethodNotFound: Çağırılan API metodunun bulunamadığını bildirir.
HTTP 429 - TooManyRequests: API limitlerinin aşıldığını bildirir. TheNextReset altında API'ın taleplere cevap verebileceği tarih-saate kalan süre Unix Time formatında bulunur.
HTTP 500 - ServiceException: Beklenmeyen bir hatayı bildirir. ErrorMessage altında detaylı açıklama bulunur.

API Referansları

Switch API, Switch DB işlemleri için 6 temel referans barındırır.

POST /Add

Switch DB'de oluşturduğunuz bir listeye veri seti eklemek için kullanılır. Header'da gönderilen List parametresi ile veri setinin ekleneceği listeyi seçebilirsiniz. İlişkisel veritabanlarındaki INSERT komutunun karşılığıdır. Request body'de veritabanına eklenecek veri seti iletilir. API v1.2.1 sonrasında, gönderilen verinin array olması durumunda array içindeki her bir item tek tek eklenir, böylece toplu ekleme işlemi sağlanır.

Headers:
APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
List: {{LIST_NAME}}
                        
Body:
{
    "BookGuid" : "2D72BCE5-2897-4C52-BD22-D5079DA5C976",
    "Title" : "Lorem Ipsum Dolor",
    "Author" : "Sit Amet",
    "IsActive" : 1
}
                        
v1.2.1 ve sonrasında toplu ekleme için Body:
[
    {
        "BookGuid" : "2D72BCE5-2897-4C52-BD22-D5079DA5C976",
        "Title" : "Lorem Ipsum Dolor",
        "Author" : "Sit Amet",
        "IsActive" : 1
    },
    {
        "BookGuid" : "0DE4F077-6D00-4EA6-B7A0-33427FFD01F5",
        "Title" : "Consectetur Adipiscing Elit",
        "Author" : "Maecenas Faucibus",
        "IsActive" : 1
    }
]
                        
Response:
{
    "ResponseTime": "2016-09-15T04:09:32.1757041+03:00",
    "Response": "Success",
    "ListItemId": "570d9559f6746431da1fc7ab"
}
                        

POST /Set

Switch DB'de daha önce eklemiş olduğunuz bir veriyi güncellemek için kullanılır. Header'da gönderilen List parametersi düzenlemenin yapılacağı listeyi belirtir. ListItemId parametresi düzenlenecek veri için Switch DB tarafından oluşturulan ID'yi belirtir. İlişkisel veritabanlarındaki UPDATE komutunun karşılığıdır. Request body'de veritabanına düzenlenecek veri seti iletilir.

Headers:
APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
List: {{LIST_NAME}}
ListItemId: {{LIST_ITEM_ID}}
                        
Body:
{
    "BookGuid" : "2D72BCE5-2897-4C52-BD22-D5079DA5C976",
    "Title" : "Lorem Ipsum Sit",
    "Author" : "Dolor Amet",
    "IsActive" : 0
}
                        
Response:
{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": "Success"
}
                        

DELETE /Set

Switch DB'de daha önce eklemiş olduğunuz bir veriyi silmek için kullanılır. Header'da gönderilen List parametersi silme işleminin yapılacağı listeyi belirtir. ListItemId parametresi silinecek veri için Switch DB tarafından oluşturulan ID'yi belirtir. İlişkisel veritabanlarındaki DELETE komutunun karşılığıdır.

Headers:
APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
List: {{LIST_NAME}}
ListItemId: {{LIST_ITEM_ID}}
                        
Response:
{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": "Success"
}
                        

POST /List

Switch DB'de daha önce eklemiş olduğunuz bir veriyi listelemek için kullanılır. Header'da gönderilen List parametersi listeleme işleminin yapılacağı listeyi belirtir. İlişkisel veritabanlarındaki SELECT komutunun karşılığıdır.

Headers:
APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
List: {{LIST_NAME}}
                        

Body altında belirtilen count parametresi listelenecek öğe sayısını belirtir. Limitsiz olması için -1 değerini verebilirsiniz. Page parametresi count parametresindeki öğe sayısına göre oluşan sayfalar arasında gezinmenizi sağlar. İlk sayfa için 0 değerini verebilirsiniz. Where parametresi altında birden fazla koşul tanımlaması yapabilirsiniz. Where parametresi altında type, column ve value parametreleri bulunur. Type parametresinin alabileceği değerler aşağıda açıklanmıştır. Column parametresinde karşılaştırmanın yapılacağı nesne adı verilir. Value parametresinde karşılaştırmanın yapılacağı değer verilir.

Where Tipleri

Where ile birden birden fazla koşul kontrolü tanımlayabilirsiniz. Tanımlayabileceğiniz koşul kontrolleri:

  • equal: Eşitlik kontrolü yapar. İlişkisel veritabanlarındaki = operatörünün karşılığıdır.
  • notEqual: Eşitsizlik kontrolü yapar. İlişkisel veritabanlarındaki != operatörünün karşılığıdır.
  • like: Benzerlik kontrolü yapar. İlişkisel veritabanlarındaki LIKE operatörünün karşılığıdır.
  • greaterThan: Büyüklük kontrolü yapar. İlişkisel veritabanlarındaki > operatörünün karşılığıdır.
  • lessThan: Küçüklük kontrolü yapar. İlişkisel veritabanlarındaki < operatörünün karşılığıdır.

Order parametresi sonuçların sıralanma şeklini değiştirir. Tip olarak ASC ve DESC değerlerini destekler. By parametresi altında sıralanacak nesne adı verilir.

v1.2 ve sonrası için

whereType parametresi altında AND ve OR tiplerini kullanarak verilen where kriterlerinin uygulanma şeklini belirleyebilirsiniz.

Body:
{
   "list":"{{LIST_NAME}}",
   "count":{{ITEM_COUNT}},
   "page":{{PAGE_NUMBER}},
   "whereType": {{WHERE_OPERATOR}} // Optional
   "where":[
      {
         "type":"{{WHERE_TYPE}}",
         "column":"{{COLUMN_NAME}}",
         "value":"{{COLUMN_VALUE}}"
      },
      {
         "type":"{{WHERE_TYPE}}",
         "column":"{{COLUMN_NAME}}",
         "value":"{{COLUMN_VALUE}}"
      }
   ],
   "order":{
      "type":"{{ORDER_TYPE}}",
      "by":"{{COLUMN_NAME}}"
   }
}
                        
Response:
{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": "Success"
}
                        

POST /SendGrid/Send

Switch API kullanarak SendGrid aracılığıyla e-posta göndermenizi sağlar. E-posta'nın içeriği request body'de gönderilir. Bu metodu kullanabilmek için öncelikle geliştirici portalı üzerinden Ayarlar sekmesine gelip SendGrid hesabınızı sisteme tanıtmanız gerekmektedir. Bu çağrıyı yapan AccessToken Write yetkisine sahip olmalıdır.

Headers:
APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
                        
Body:
{
    "personalizations": [
      {
          "to": [
          {
              "email": "[email protected]"
          }
          ],
          "subject": "Mail Subject"
      }
    ],
    "from": {
      "email": "[email protected]",
      "name": "Lorem Ipsum"
    },
    "content": [
      {
          "type": "text/html",
          "value": "<b>Hello</b>, Email!"
      }
    ]
}
                        
Response:
{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": "Success"
}
                        

GET /Lists

Geliştirici portalı'ndan oluşturduğunuz veritabanı listelerine erişmek için kullanılır. Bu fonksiyonu kullanabilmek için API Uygulama Anahtarınızın Yönetici (Administrator) yetkisine sahip olması gerekir.

Headers:
APIKey: {{API_KEY}}
AccessToken: {{ACCESS_TOKEN}}
                        
Response:
{
    "ResponseTime": "2016-09-15T04:10:14.1289240+03:00",
    "Response": ["List1", "List2", "List3"]
}
                        

Versiyon Günlüğü

v1.0 asteroid

  • Geliştirici portalı kullanıma sunuldu.
  • Add, Set ve List fonksiyonları hazırlandı.
  • Geliştirici portalı üzerinden API kullanım raporları alınabilir duruma getirildi.

v1.1 big bang

  • Geliştirici portalı üzerinden veritabanı altındaki listelere import-export desteği getirildi.
  • CDN dağıtımları etkinleştirildi.
  • Veritabanı listelerinde index oluşturma özelliği eklendi. BETA

v1.2 cosmos

  • WHERE parametresinde verilen filtrelerin uygulanma biçimini AND ya da OR olarak değiştirebilen whereType operatörü eklendi.
  • Veritabanı taşıma özelliğiyle başta seçilen lokasyondan başka bir lokasyona geçiş kolaylaştırıldı. BETA
  • Veritabanı listelerinde index oluşturma özelliği artık beta değil! RELEASE
  • Sizlerden gelen taleplerle 1 yeni veri servisi eklendi:
  • 1. Artık Switch API kullanarak SendGrid aracılığıyla e-posta gönderebilirsiniz. BETA

v1.2.1 cosmos

  • Add fonksiyonunda verinin array olarak gönderilmesi durumunda toplu ekleme yapılabilme özelliği eklendi. BETA
  • API uygulama anahtarlarına Yönetici (Administrator) yetkisi eklendi. Bu yetki ile veritabanınızdaki bazı yönetimsel işlemleri API üzerinden yapabilirsiniz. BETA
  • Yeni eklenen Lists fonksiyonu ile yönetici yetkisine sahip uygulama anahtarınızla veritabanınızdaki listelere erişebilirsiniz. BETA
  • Sizlerden gelen taleplerle 1 yeni uygulama ve 2 yeni kütüphane eklendi:
  • 1. Artık Switch Database Explorer uygulamasını kullanarak veritabanı üzerindeki işlemlerinizi kolayca gerçekleştirebilirsiniz. Uygulamayı indirmek için geliştirici portalınıza giriş yapabilirsiniz. BETA
  • 2. C# için senkron ve asenkron API erişimi sağlayan Switch API Connector kütüphanesi yayınlandı. GitHub ve NuGet üzerinden indirebilirsiniz.
  • 3. JavaScript için API erişimi sağlayan Switch API Connector kütüphanesi yayınlandı. Switch API CDN üzerinden indirebilir ya da kullanabilirsiniz.

v1.3 discovery Closed BETA

Bu sürüm henüz iç test aşamasındadır!

  • Veritabanı taşıma özelliği artık beta değil! RELEASE
  • Sizlerden gelen taleplerle 2 yeni veri servisi eklendi:
  • 1. Artık Switch API kullanarak Amazon Web Services S3 aracılığıyla upload yapabilir, birtakım bucket yönetim işlemini sağlayabilirsiniz. BETA
  • 2. Artık Switch API kullanarak Microsoft Azure Blob Storage aracılığıyla upload yapabilir, birtakım blob yönetim işlemini sağlayabilirsiniz. BETA
  • SendGrid ile e-posta gönderim özelliği artık beta değil! RELEASE